diff --git a/.agent/workflows/devtrail-status.md b/.agent/workflows/devtrail-status.md deleted file mode 100644 index e0cdefa..0000000 --- a/.agent/workflows/devtrail-status.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -description: Show DevTrail documentation status. Use to verify if AI agents properly documented their changes. ---- - -# DevTrail Status Skill - -This skill checks the documentation status of the DevTrail in the current project. - -## Instructions - -When invoked, perform the following checks and display the results: - -### 1. Find Recent DevTrail Documents - -Search for DevTrail documents created or modified in the last hour: - -```bash -# Get documents modified in the last hour -git log --since="1 hour ago" --name-only --pretty=format: -- ".devtrail/**/*.md" | sort -u | grep -v "^$" -``` - -If git is not available or the directory is not a git repo, use file modification times. -Check these directories for each document type: - -| Type | Prefix | Directory | -|------|--------|-----------| -| AILOG | `AILOG-` | `.devtrail/07-ai-audit/agent-logs/` | -| AIDEC | `AIDEC-` | `.devtrail/07-ai-audit/decisions/` | -| ADR | `ADR-` | `.devtrail/04-architecture/decisions/` | -| ETH | `ETH-` | `.devtrail/07-ai-audit/ethical-reviews/` | -| REQ | `REQ-` | `.devtrail/03-requirements/` | -| TES | `TES-` | `.devtrail/05-testing/` | -| INC | `INC-` | `.devtrail/06-operations/incidents/` | -| TDE | `TDE-` | `.devtrail/06-operations/tech-debt/` | -| SEC | `SEC-` | `.devtrail/08-security/` | -| MCARD | `MCARD-` | `.devtrail/09-ai-models/` | -| SBOM | `SBOM-` | `.devtrail/07-ai-audit/` | -| DPIA | `DPIA-` | `.devtrail/07-ai-audit/ethical-reviews/` | - -### 2. Find Modified Source Files - -Identify source files that were modified and might need documentation: - -```bash -# Get modified files (staged and unstaged) -git diff --name-only HEAD~1..HEAD 2>/dev/null || git diff --name-only -``` - -Filter to show only files that might need documentation: -- Exclude: `*.md`, `*.json`, `*.yml`, `*.yaml`, `*.lock`, `package-lock.json` -- Include: `*.ts`, `*.js`, `*.tsx`, `*.jsx`, `*.py`, `*.go`, `*.rs`, `*.java`, `*.cs`, `*.rb`, `*.php` - -### 3. Analyze Documentation Gaps - -For each modified source file, check if there's a corresponding DevTrail document: -- Files with >10 lines of changes in business logic folders should have an AILOG -- Security-related files (auth, crypto, secrets) should have a SEC assessment -- Architecture/structural changes should have an ADR -- AI/ML model changes should have a MCARD -- Dependency changes (`package.json`, `Cargo.toml`, `go.mod`, etc.) should have an SBOM -- Changes involving personal data processing should have a DPIA -- Test files should have a TES record -- Bug fixes or incidents should have an INC record - -### 4. Display Results - -Format the output as follows: - -``` -DevTrail Status -================================================================================ - -Recent Documents (last hour): - ✅ AILOG-2025-01-27-001-implement-auth.md - ✅ AIDEC-2025-01-27-001-auth-strategy.md - -Modified Files Without Documentation: - ⚠️ src/auth/login.ts (47 lines changed) - ⚠️ src/api/users.ts (23 lines changed) - -Summary: - Documents created: 2 - Files needing review: 2 - -Use /devtrail-new to create documentation for undocumented changes. -``` - -### Symbol Legend - -- ✅ = Documentation exists -- ⚠️ = May need documentation -- ℹ️ = Informational - -### Edge Cases - -1. **No git repository**: Show message explaining git is required for full functionality -2. **No recent documents**: Show "No DevTrail documents created in the last hour" -3. **No modified files**: Show "No source files modified recently" -4. **Empty .devtrail directory**: Show warning that DevTrail may not be properly set up - -### Additional Notes - -- This skill is read-only and does not create or modify files -- Run this after completing development tasks to verify documentation compliance -- If files need documentation, remind the user of the DevTrail rules diff --git a/.agent/workflows/devtrail-adr.md b/.agent/workflows/straymark-adr.md similarity index 85% rename from .agent/workflows/devtrail-adr.md rename to .agent/workflows/straymark-adr.md index c0db864..1080b11 100644 --- a/.agent/workflows/devtrail-adr.md +++ b/.agent/workflows/straymark-adr.md @@ -2,7 +2,7 @@ description: Create an ADR (Architecture Decision Record) for significant architectural decisions. Requires human review. --- -# DevTrail ADR Skill +# StrayMark ADR Skill Create an Architecture Decision Record (ADR) for significant architectural decisions. @@ -22,7 +22,7 @@ date +%Y-%m-%d git diff --stat HEAD~1 2>/dev/null || git diff --stat # Check for related ADRs -ls .devtrail/02-design/decisions/ADR-*.md 2>/dev/null | tail -5 +ls .straymark/02-design/decisions/ADR-*.md 2>/dev/null | tail -5 ``` ### 2. Confirm with User @@ -31,7 +31,7 @@ ls .devtrail/02-design/decisions/ADR-*.md 2>/dev/null | tail -5 ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail ADR ║ +║ StrayMark ADR ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ ⚠️ ADRs require human review after creation. ║ @@ -54,14 +54,14 @@ ls .devtrail/02-design/decisions/ADR-*.md 2>/dev/null | tail -5 ```bash # Count existing ADRs for today -ls .devtrail/02-design/decisions/ADR-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/02-design/decisions/ADR-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ### 4. Check Language and Load Template -Read `.devtrail/config.yml` for language setting: -- `en` (default): `.devtrail/templates/TEMPLATE-ADR.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-ADR.md` +Read `.straymark/config.yml` for language setting: +- `en` (default): `.straymark/templates/TEMPLATE-ADR.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-ADR.md` ### 5. Create Document @@ -86,18 +86,18 @@ Fill template with: - Implementation Plan: High-level steps - Success Metrics: How to validate the decision -Save to: `.devtrail/02-design/decisions/ADR-YYYY-MM-DD-NNN-description.md` +Save to: `.straymark/02-design/decisions/ADR-YYYY-MM-DD-NNN-description.md` ### 6. Report Result ``` ⚠️ ADR created (requires human review): - .devtrail/02-design/decisions/ADR-YYYY-MM-DD-NNN-description.md + .straymark/02-design/decisions/ADR-YYYY-MM-DD-NNN-description.md Status: draft Review Required: YES -DevTrail: Created ADR-YYYY-MM-DD-NNN-description.md (review required) +StrayMark: Created ADR-YYYY-MM-DD-NNN-description.md (review required) ``` ## Examples of Architectural Decisions diff --git a/.agent/workflows/devtrail-aidec.md b/.agent/workflows/straymark-aidec.md similarity index 83% rename from .agent/workflows/devtrail-aidec.md rename to .agent/workflows/straymark-aidec.md index ae60ca8..4830888 100644 --- a/.agent/workflows/devtrail-aidec.md +++ b/.agent/workflows/straymark-aidec.md @@ -2,7 +2,7 @@ description: Create an AIDEC (AI Decision) document to record a technical decision with alternatives considered. --- -# DevTrail AIDEC Skill +# StrayMark AIDEC Skill Create an AI Decision (AIDEC) document to record technical decisions and the alternatives considered. @@ -26,7 +26,7 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail AIDEC ║ +║ StrayMark AIDEC ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ 📋 AIDEC documents a decision between alternatives. ║ @@ -43,14 +43,14 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat ```bash # Count existing AIDECs for today -ls .devtrail/07-ai-audit/decisions/AIDEC-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/07-ai-audit/decisions/AIDEC-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ### 4. Check Language and Load Template -Read `.devtrail/config.yml` for language setting: -- `en` (default): `.devtrail/templates/TEMPLATE-AIDEC.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-AIDEC.md` +Read `.straymark/config.yml` for language setting: +- `en` (default): `.straymark/templates/TEMPLATE-AIDEC.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-AIDEC.md` ### 5. Create Document @@ -69,15 +69,15 @@ Fill template with: - Decision: Which was chosen and justification - Consequences: Positive, negative, and risks -Save to: `.devtrail/07-ai-audit/decisions/AIDEC-YYYY-MM-DD-NNN-description.md` +Save to: `.straymark/07-ai-audit/decisions/AIDEC-YYYY-MM-DD-NNN-description.md` ### 6. Report Result ``` ✅ AIDEC created: - .devtrail/07-ai-audit/decisions/AIDEC-YYYY-MM-DD-NNN-description.md + .straymark/07-ai-audit/decisions/AIDEC-YYYY-MM-DD-NNN-description.md -DevTrail: Created AIDEC-YYYY-MM-DD-NNN-description.md +StrayMark: Created AIDEC-YYYY-MM-DD-NNN-description.md ``` ## When to Create an AIDEC diff --git a/.agent/workflows/devtrail-ailog.md b/.agent/workflows/straymark-ailog.md similarity index 82% rename from .agent/workflows/devtrail-ailog.md rename to .agent/workflows/straymark-ailog.md index 81186a1..cb6cbd0 100644 --- a/.agent/workflows/devtrail-ailog.md +++ b/.agent/workflows/straymark-ailog.md @@ -2,7 +2,7 @@ description: Create an AILOG (AI Action Log) document for the current changes. Quick shortcut for the most common document type. --- -# DevTrail AILOG Skill +# StrayMark AILOG Skill Quickly create an AI Action Log (AILOG) document for the current changes. @@ -29,7 +29,7 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail AILOG ║ +║ StrayMark AILOG ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ 📊 Changes detected: ║ @@ -47,16 +47,16 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat ```bash # Count existing AILOGs for today -ls .devtrail/07-ai-audit/agent-logs/AILOG-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/07-ai-audit/agent-logs/AILOG-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` Next number = count + 1, formatted as 3 digits (001, 002, etc.) ### 4. Check Language and Load Template -Read `.devtrail/config.yml` for language setting: -- `en` (default): `.devtrail/templates/TEMPLATE-AILOG.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-AILOG.md` +Read `.straymark/config.yml` for language setting: +- `en` (default): `.straymark/templates/TEMPLATE-AILOG.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-AILOG.md` ### 5. Create Document @@ -68,15 +68,15 @@ Fill template with: - `confidence`: based on change complexity - `risk_level`: based on files modified -Save to: `.devtrail/07-ai-audit/agent-logs/AILOG-YYYY-MM-DD-NNN-description.md` +Save to: `.straymark/07-ai-audit/agent-logs/AILOG-YYYY-MM-DD-NNN-description.md` ### 6. Report Result ``` ✅ AILOG created: - .devtrail/07-ai-audit/agent-logs/AILOG-YYYY-MM-DD-NNN-description.md + .straymark/07-ai-audit/agent-logs/AILOG-YYYY-MM-DD-NNN-description.md -DevTrail: Created AILOG-YYYY-MM-DD-NNN-description.md +StrayMark: Created AILOG-YYYY-MM-DD-NNN-description.md ``` ## Risk Level Guidelines diff --git a/.agent/workflows/straymark-audit-execute.md b/.agent/workflows/straymark-audit-execute.md new file mode 100644 index 0000000..c838825 --- /dev/null +++ b/.agent/workflows/straymark-audit-execute.md @@ -0,0 +1,150 @@ +--- +description: Execute an external audit of a Charter inside an auditor-side CLI (gemini-cli, claude-cli, copilot-cli, codex-cli). Reads the resolved audit prompt from the canonical location, audits with tool use, writes the report. Operator invokes one instance per CLI. +--- + +# StrayMark Audit Execute Skill + +Execute an external audit of a Charter inside this CLI session. Read the resolved audit prompt that StrayMark prepared at the canonical location, audit the implementation with tool use (citing `path:line` of files actually opened), and write the report at the canonical location for the audit-review skill to consolidate later. + +## When to invoke + +This skill runs **inside an auditor-side CLI** (gemini-cli, claude-cli, copilot-cli, codex-cli, or any agent runtime configured with read-only access to the adopter's repo). The operator opens the CLI in the repo, then invokes `/straymark-audit-execute `. + +The skill is the second step of the v1 audit cycle: + +1. In the main IDE: operator runs `/straymark-audit-prompt CHARTER-NN` → StrayMark writes `.straymark/audits/CHARTER-NN/audit-prompt.md`. +2. **(this skill)** Operator opens an auditor-side CLI in the repo and runs `/straymark-audit-execute CHARTER-NN`. Repeat in N CLIs (recommended: ≥2 of different model families). +3. When ALL audits commissioned have completed, operator returns to the main IDE and runs `/straymark-audit-review CHARTER-NN`. + +## Instructions + +### 1. Resolve the Charter + +The argument is optional. Two cases: + +**Case A — argument provided** (`/straymark-audit-execute CHARTER-04`): +Use the literal value. Construct the audit dir path: `.straymark/audits/CHARTER-04/`. + +**Case B — argument omitted** (`/straymark-audit-execute`): +Auto-discover pending prompts. Detect this auditor's model identifier (see step 2 for how) and produce its slug. Then: + +```bash +# List all audit prompts that exist +ls .straymark/audits/*/audit-prompt.md 2>/dev/null +``` + +For each found `.straymark/audits//audit-prompt.md`, check whether a report from this model already exists at `.straymark/audits//report-.md`. The set of "pending" prompts is the ones WITHOUT a corresponding report. + +- **Exactly one pending** → proceed with that CHARTER-ID, announcing the choice to the operator. +- **Multiple pending** → list them numerically with their Charter titles (read the title from the resolved prompt's `# Auditoría de Charter — CHARTER-NN` heading) and ask the operator to pick one. +- **None pending** → message: "No pending audit prompts for this model under `.straymark/audits/`. Either the operator has not run `/straymark-audit-prompt` in the main agent yet, or all the prompts already have a report from this model. Verify with the operator." + +### 2. Detect this auditor's model identifier + +Identify the model running this CLI session and produce a filesystem-safe slug. + +The operator will know the canonical model id of the auditor running this skill (for example `claude-sonnet-4-6`, `claude-opus-4-7`, `gemini-2.5-pro`, `gpt-5.3-codex`, `copilot-v1.0.40`). Slug rules: + +- Lowercase ASCII. +- Replace any character that isn't `[a-z0-9-]` with `-`. +- Collapse consecutive dashes to one. +- Trim leading/trailing dashes. + +Examples: + +| Model identifier | Slug | +|---|---| +| `claude-sonnet-4-6` | `claude-sonnet-4-6` | +| `gemini-2.5-pro` | `gemini-2-5-pro` | +| `gpt-5.3-codex` | `gpt-5-3-codex` | +| `copilot-v1.0.40` | `copilot-v1-0-40` | + +If the runtime does not expose the model identifier directly, ask the operator to confirm before proceeding. Do NOT fabricate a slug — collisions or wrong identifiers corrupt the review step. + +### 3. Read the audit prompt + +```bash +cat .straymark/audits//audit-prompt.md +``` + +The prompt is self-contained: it includes the Charter content, originating AILOGs, git diff, and the discipline rules (REGLA ABSOLUTA — SOLO LECTURA, evidence-citation discipline, severity calibration). Read it carefully before auditing. + +### 4. Audit with tool use + +Follow the prompt literally, with these expectations: + +- **Read-only**: never write to project files. The only output you are allowed to produce is the report at the canonical path in step 5. +- **Tool-use evidence**: every finding you record must cite `path:line` of files you actually opened via `Read`, `Grep`, or equivalent. Do not infer behavior from file names alone. +- **Severity calibration**: open the active configuration (factories, env defaults, build tags, deployment scaling) before declaring Critical/High severity. The Etapa 12 example in the prompt is a real case of inflation that the calibration discipline catches. +- **Scope discipline**: only report findings inside the Charter's declared scope. Out-of-scope observations go in their own section, not as defects. + +Track how many `path:line` citations you accumulate — it goes in the report frontmatter as `evidence_citations`. + +### 5. Write the report + +Output path: + +``` +.straymark/audits//report-.md +``` + +If a report at that exact path already exists (re-run on the same Charter with the same model), warn the operator before overwriting. The default is to overwrite — re-runs replace stale reports rather than coexist with them. + +If, by some unusual reason, two distinct sessions of the SAME model audited the same Charter and the operator wants both, append a numeric suffix manually: `report--2.md`. + +The report frontmatter MUST conform to `audit-output.schema.v0.json`: + +```yaml +--- +audit_role: auditor +auditor: # e.g., claude-sonnet-4-6 +charter_id: +git_range: "" +prompt_used: audit-prompt.md +audited_at: +findings_total: +findings_by_category: + hallucination: + implementation_gap: + real_debt: + false_positive: +evidence_citations: # how many path:line citations the body contains +audit_quality: high | medium | low +--- + +# (body following the format declared in the prompt's "Formato de salida" section) +``` + +### 6. Notify the operator — with the wait warning + +After writing the report, print this message verbatim (substituting ``, ``, and the finding count): + +``` +Audit complete for (this auditor: ). + + Report: .straymark/audits//report-.md + Findings: total () + +IMPORTANT: do NOT return to the main agent for /straymark-audit-review yet +unless ALL audits you commissioned have completed. + +If you opened other auditor CLIs (gemini-cli, copilot-cli, codex-cli, ...) +and have not yet seen their /straymark-audit-execute finish, wait for them. +Invoking /straymark-audit-review with incomplete reports produces a partial +consolidated analysis that you will have to discard or re-run — costing +you the audit cycle. + +When and only when ALL audits you commissioned are complete, return to +your main IDE and run: + + /straymark-audit-review +``` + +This wait warning matters: an operator with three CLIs open in parallel can be tempted to invoke review as soon as the first audit finishes. The review skill iterates whatever reports are present at the time it runs; it cannot wait for additional reports to arrive. + +## Notes + +- **No HTTP API calls.** This skill runs inside an auditor CLI that the operator chose; that CLI handles all model invocation, API keys, and rate limits. StrayMark orchestrates prompt resolution and report shape — nothing else. +- **Re-runs**: if you invoke this skill on a Charter whose report from this model already exists, the existing one is overwritten. The previous report is lost — if you wanted to keep it, copy it manually before re-running. +- **Multiple Charters in the same CLI session**: invoke the skill once per Charter. Reports do not collide because the filename is keyed on Charter id + model slug. +- **Heterogeneity inter-family**: the skill does not enforce that the operator uses different model families across the N audit-execute invocations. The recommendation is in the audit prompt itself and in `AGENT-RULES.md` §12; trust the operator. diff --git a/.agent/workflows/straymark-audit-prompt.md b/.agent/workflows/straymark-audit-prompt.md new file mode 100644 index 0000000..e8900c9 --- /dev/null +++ b/.agent/workflows/straymark-audit-prompt.md @@ -0,0 +1,83 @@ +--- +description: Generate the unified audit prompt for a Charter at the canonical filesystem location. The operator then opens N auditor-side CLIs (gemini-cli, claude-cli, copilot-cli, etc.) and invokes /straymark-audit-execute in each — no copy/paste. Counterpart of /straymark-audit-review. +--- + +# StrayMark Audit Prompt Skill + +Generate the unified audit prompt for a Charter and write it to the canonical filesystem location. The operator then opens auditor-side CLIs in the same repo and invokes `/straymark-audit-execute` — the audit prompt is read directly from disk by each auditor; the operator never copies/pastes. + +## When to invoke + +Use this skill when the developer agreed to run an external audit at the Charter checkpoint (see `.straymark/00-governance/AGENT-RULES.md` § Audit checkpoint). + +The Charter should be in `in-progress` or `declared` status — auditing closed Charters is allowed but atypical (warn the operator and proceed only on confirmation). + +## Instructions + +### 1. Resolve the Charter + +Argument: a Charter identifier (`CHARTER-04`, `04`, or full id with slug). + +```bash +straymark charter status +``` + +Verify the Charter exists and capture its `status`. If `status: closed`, surface a one-line warning to the operator and ask whether to proceed. + +### 2. Generate the unified audit prompt + +```bash +straymark charter audit --prepare +``` + +The CLI writes the resolved prompt to: + +``` +.straymark/audits//audit-prompt.md +``` + +The prompt is self-contained: it embeds the Charter content, the originating AILOGs, the git diff over the resolved range (default `origin/main..HEAD`, falls back to `HEAD~1..HEAD` if no upstream is reachable), and the discipline rules (REGLA ABSOLUTA — SOLO LECTURA, evidence-citation, severity calibration). The prompt template lifts the seven universal sections from Sentinel's pre-StrayMark audit skill and parameterizes the project-specific hardcodes. + +The CLI does NOT invoke any LLM. It only resolves placeholders. + +### 3. Notify the operator + +After the CLI succeeds, print this guidance verbatim (substituting ``): + +``` +Audit prompt prepared for . + + Location: .straymark/audits//audit-prompt.md + (informational — you don't need to copy this path anywhere) + +Next steps: + + 1. Open one or more auditor-side CLIs (gemini-cli, claude-cli, + copilot-cli, codex-cli — whatever you have) in this repo. Each + CLI session uses its own model; recommendation is at least 2 + auditors of DIFFERENT model families, so cross-family blind + spots become signal when their findings converge. + + 2. In each auditor CLI, invoke: + + /straymark-audit-execute + + The skill is already installed (straymark init copies it to all + three platform locations). It reads the prompt from disk + automatically — you do not need to copy/paste anything. + + 3. When and only when ALL audits you commissioned have completed, + return to this main agent and run: + + /straymark-audit-review + + Reviewing with incomplete reports gives you a partial consolidated + analysis that you will have to discard or re-run. +``` + +## Notes + +- This skill is **orchestration-only**. It does NOT invoke LLM APIs, decide which models the operator uses, or wait for responses. It runs the CLI's `--prepare`, points the operator at the next-step skill, and exits. +- Re-running the skill on the same Charter regenerates the prompt at the same path. It does NOT touch operator-saved reports under `.straymark/audits//report-*.md`. +- Heterogeneity inter-family is recommended but not enforced in v0; the operator decides the model pairing across the N CLIs they open. +- For the rationale on cross-family auditors, see `dist/.straymark/audit-prompts/audit-prompt.md` § Tu rol or `Propuesta/straymark-cli-roadmap.md` §5.2 in the upstream repo. diff --git a/.agent/workflows/straymark-audit-review.md b/.agent/workflows/straymark-audit-review.md new file mode 100644 index 0000000..b978192 --- /dev/null +++ b/.agent/workflows/straymark-audit-review.md @@ -0,0 +1,251 @@ +--- +description: Consolidate N external auditor reports into a critical review document with verdicts, remediation plan, and auditor ratings. Then merge the external_audit YAML block into the Charter telemetry. Counterpart of /straymark-audit-prompt and /straymark-audit-execute. +--- + +# StrayMark Audit Review Skill + +Critically evaluate the N external auditor reports for a Charter, cross-reference each finding against the actual source code, and produce a consolidated `review.md` with verdicts, a prioritized remediation plan, and per-auditor ratings. Then merge the `external_audit` YAML block into the Charter telemetry. + +This is the third and final step of the v1 audit cycle, and it is where the substance lives — the calibrator role (definitional reconciliation across heterogeneous auditor verdicts) is now performed by the main agent inline, replacing the v0 paste-based calibrator-reconciler prompt. + +## When to invoke + +After the operator has commissioned the audits in N auditor-side CLIs (each running `/straymark-audit-execute `) and **all of them have completed**. The operator returns to the main IDE and invokes: + +``` +/straymark-audit-review +``` + +If only some audits have completed, **do not proceed** — invoking the skill with incomplete reports produces a partial consolidated analysis. Verify with the operator that all the CLIs they opened have finished writing their reports under `.straymark/audits//report-*.md`. + +## Instructions + +### 1. Resolve the Charter and verify report set + +Argument: a Charter identifier. + +```bash +ls -la .straymark/audits// +``` + +Confirm: + +- `audit-prompt.md` exists (the prepared prompt the auditors read). +- `report-*.md` files exist (one per auditor that completed). At least 2 reports are recommended for cross-family heterogeneity to deliver signal; warn (do not block) if only 1 report is present. +- Match each `report-.md` filename against the model identifier in its frontmatter (`auditor:` field) to confirm consistency. Discrepancies are surfaced to the operator. + +If only the prompt is present and no reports exist, instruct the operator to run `/straymark-audit-execute` in the auditor CLIs first. + +### 2. Read all auditor reports + extract finding master list + +For each `.straymark/audits//report-*.md`: + +- Validate the frontmatter against `audit-output.schema.v0.json` (the CLI does this in step 6, but a soft check here gives an earlier and more readable error if any report is malformed). +- Extract: model identifier, total findings, findings by category, evidence_citations count, audit_quality. +- Parse the body for finding entries (typically `## Findings` → `### F1 — title — category` blocks with `Where:`, `What I observed:`, `Why I'm flagging it:`). + +Build a **master finding list** — every unique claim across all auditors, deduplicated when two auditors clearly describe the same thing. + +### 3. Verify every finding against actual code + +This is the substantive step. For EACH finding in the master list: + +**Launch Explore agents in parallel** (up to 3 at a time) to verify findings. Group findings by the file they reference and send related findings to the same agent. + +For each finding, the verification answers four questions: + +1. **Does the code actually have this problem?** Read the cited `path:line`. Is the claim accurate? +2. **Is it in scope?** Does the finding affect a task or file declared in the Charter? If it's outside the Charter's scope, classify as `MISATTRIBUTED`. +3. **What's the real severity given the CURRENT configuration?** Check active driver, feature flags, build tags, DB role, deployment scope (the calibration discipline from the audit prompt). The Etapa 12 example in the prompt is a real case of inflation that careful calibration catches. +4. **Is it a duplicate?** Does another auditor report the same finding differently? + +#### Verdict classification + +Each finding gets one of these verdicts: + +- **VALID** — Real problem, in scope, correctly described, correctly severized. +- **PARTIALLY VALID** — Real observation but wrong severity, missing nuance, or triggers only under a config not active in main. Include the reclassification. +- **MISATTRIBUTED** — Real observation but belongs to a different Charter or scope unit. +- **FALSE POSITIVE** — Claim is factually incorrect (file exists, code works as expected, the assumed driver isn't active, etc.). +- **DUPLICATE** — Same finding reported by another auditor (reference the original). + +#### Severity reclassification + +When the auditor's severity does not match the active configuration: + +- **Inflation** (auditor says Critical/High, code confirms only conditional): downgrade to Medium with explicit note on what config would activate it, OR move to "post-Charter / no bloqueante" if the trigger is a component not yet implemented. +- **Deflation** (auditor says Low/None, code shows a real trigger in current config): upgrade with evidence from the code path that activates it. +- **Correct inflation** (auditor says Critical and config confirms it): keep. + +An auditor that consistently inflates or deflates loses points in the auditor rating (step 5). + +### 4. Identify findings the auditors missed + +Based on your code exploration, check whether there are problems the auditors did NOT find. Focus on: + +- Security: SQL queries missing ownership filters, missing transaction boundaries, secrets in logs. +- Logic: input parameters ignored, dead code paths, unreachable branches. +- Consistency: naming mismatches between layers (model vs handler vs API). + +Mark these as "Missed by all auditors" in the remediation plan. + +### 5. Build the consolidated review.md + +Write the consolidated analysis to `.straymark/audits//review.md` with this structure (six sections, lifted from Sentinel's pre-StrayMark audit-review skill): + +```markdown +--- +audit_role: calibrator-reconciler +calibrator: +charter_id: +git_range: "" +prompt_used: ../audit-prompt.md +calibrated_at: +auditors_reconciled: + - report-.md + - report-.md + - ... +findings_consolidated: +findings_by_status: + agreed: + disputed: + unique_: + unique_: + rejected: +--- + +# Consolidated audit review — + +**Reviewer:** +**Date:** +**Confidence:** [High | Medium] + +## 1. Executive summary + +[2-3 paragraphs. Total findings count, scope confusion if any, most critical bug, +overall verdict on the Charter's implementation.] + +## 2. Scope definition + +[Table of Charter tasks, the closing criterion, and what IS vs IS NOT in scope +of this Charter. The auditors' findings are evaluated against THIS scope.] + +## 3. Per-auditor evaluation + +### 3.1 (model: ) + +| # | Finding | Reported severity | Verdict | Justification | +|---|---------|-------------------|---------|---------------| + +**Summary:** [2-3 sentences on this auditor's overall performance.] + +### 3.2 ... (same shape) + +## 4. Remediation plan — VALID and PARTIALLY VALID findings + +### P0 — Security +- **Files:** `path:line` +- **Problem:** [description with code evidence] +- **Remediation:** [specific approach] +- **Complexity:** [Low / Medium / High] +- **Detected by:** [auditor slug(s), or "Missed by all auditors" if you found it] + +### P1 — Integrity +[Same shape] + +### P2 — Consistency +[Same shape] + +### P3 — Robustness +[Same shape] + +### P4 — Documentation +[Same shape] + +## 5. Discarded findings — misattributions and false positives + +| Finding | Type | Charter / area | Auditor | +|---------|------|----------------|---------| + +## 6. Auditor ratings + +Score each auditor 1-10 across four criteria with weights: + +| Auditor | Scope precision (25%) | Technical depth (25%) | Bug detection (30%) | False positive rate (20%) | **Overall** | +|---------|:-:|:-:|:-:|:-:|:-:| +| | /10 | /10 | /10 | /10 | **/10** | +| ... + +### Justifications + +** — /10**: [2-3 sentences on what this auditor did well and where they slipped.] + +## 7. Conclusion + +[State of the Charter — clean / partial / deviated. Critical findings count. +Key remediation items the operator should address before close. +Recommended next step.] +``` + +### 6. Validate + emit external_audit YAML + +Run the CLI's merge step to validate all reports against the schema and emit the YAML block (combined with `--merge-into` if the operator's Charter telemetry already exists): + +**Branch A — telemetry exists** (operator already ran `straymark charter close` for this Charter, perhaps without audit, and is now adding audit findings retroactively): + +```bash +straymark charter audit --merge-reports \ + --merge-into .straymark/charters/.telemetry.yaml +``` + +The CLI appends the `external_audit:` array to the telemetry YAML. The CLI v1 deliberately rejects re-audit (file already has `external_audit:`) — if that fires, surface the message to the operator. Manual append is the fallback. + +**Branch B — telemetry does NOT exist** (the typical case: operator audits BEFORE closing): + +```bash +straymark charter audit --merge-reports +``` + +The YAML block prints to stdout. Capture it and write it to `.straymark/audits//external-audit-pending.yaml` so the operator can paste it into the telemetry when running `straymark charter close `. Tell the operator: "When you run `straymark charter close `, paste the `external_audit:` block from `.straymark/audits//external-audit-pending.yaml` when prompted." + +### 7. Notify the operator with a summary + +``` +Consolidated audit review complete for . + + Auditors reconciled: + Findings reported: + Findings VALID: (%) + False positives: + Misattributions: + Missed by all (you): + + Remediation plan: + P0 (Security): + P1 (Integrity): + P2-P4 (Other): + + Auditor ratings: + : /10 + : /10 + ... + + Documents written: + .straymark/audits//review.md + [either: .straymark/charters/.telemetry.yaml (merged)] + [or: .straymark/audits//external-audit-pending.yaml] + +Run `git diff` to review the changes before commit. +``` + +## Notes + +- **The calibrator role is in-conversation, not in a paste-based prompt.** v0 had a `calibrator-reconciler.md` template that the operator pasted into a separate model. v1 eliminates that round-trip — the main agent (this conversation) has filesystem access and can verify findings against code, which is what makes the consolidated review substantive instead of mechanical. +- **Heterogeneity inter-family is for the auditor pair, not the calibrator.** The calibrator (this skill, running in the main agent) may be of any family — even the same family as one of the auditors — because its task is definitional (apply the schema to already-produced verdicts), not discovery. +- **The review.md is the human-readable delivery; the YAML block is the machine-readable input to telemetry.** Both coexist by design. The operator reads `review.md`; `straymark metrics` and the Phase 2 telemetry aggregation read the YAML. +- **Re-running the skill** overwrites `review.md`. If the operator wants to keep the previous review (e.g., after a re-audit cycle), instruct them to copy it manually before re-running. +- **No HTTP API calls.** The skill runs the CLI's `--merge-reports` (which validates schemas and emits YAML), invokes Explore agents internally for code verification (which run in the main agent's context, not external APIs), and writes markdown. StrayMark does not invoke LLM APIs at any point. + +## Credit + +The six-section structure of `review.md` and the verdict vocabulary (VALID / PARTIALLY VALID / MISATTRIBUTED / FALSE POSITIVE / DUPLICATE) are lifted from the `audit-review/SKILL.md` skill mature pre-StrayMark in Sentinel, contributed via [issue #102](https://github.com/StrangeDaysTech/straymark/issues/102) by José Villaseñor Montfort (StrangeDaysTech). The four-criterion weighted auditor rating (Scope precision 25% / Technical depth 25% / Bug detection 30% / False positive rate 20%) is the same. Project-specific hardcodes parameterized. diff --git a/.agent/workflows/straymark-charter-new.md b/.agent/workflows/straymark-charter-new.md new file mode 100644 index 0000000..fcffa01 --- /dev/null +++ b/.agent/workflows/straymark-charter-new.md @@ -0,0 +1,90 @@ +--- +description: Scaffold a Charter — StrayMark's bounded unit of work that pairs declarative ex-ante scope with telemetry ex-post. Use when starting a multi-session implementation block (>1 day, >5 tasks, multi-phase). +--- + +# StrayMark Charter Scaffold Skill + +Declare a Charter at the start of a bounded, auditable unit of work — *not* every change. Charters wrap multi-session work that warrants a stable scope contract you can drift-check at close. They are conceptually distinct from the 12+4 governance document types (AILOG, ADR, AIDEC, …): Charters live at `.straymark/charters/NN-slug.md` and use a sequential prefix instead of a date prefix. + +> See `STRAYMARK.md §15` and `.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md` for the lifecycle and the SpecKit ↔ Charter bridge. + +## When to use this skill + +Trigger on any of: + +- Multi-session implementation block (>1 day, >5 tasks across phases). +- Work that warrants external audit at completion. +- A SpecKit feature has reached `tasks.md` and the operator wants a stable scope contract before `/speckit-implement`. +- The user asks to "declare", "open", or "start" a Charter. + +If the work is a single-session change → use `straymark-ailog` instead. + +## Instructions + +### 1. Gather context + +```bash +# Sequential number of the Charter being created +straymark charter list 2>/dev/null | tail -5 || true + +# Surrounding spec / AILOG context — Charters frequently originate from one +ls specs/*/spec.md 2>/dev/null | head -5 +ls .straymark/07-ai-audit/agent-logs/AILOG-*.md 2>/dev/null | tail -5 +``` + +### 2. Confirm with user + +Surface the required and optional inputs: + +- **Required**: title (one line), effort estimate (`XS | S | M | L`). +- **Optional but encouraged**: one of `--from-ailog AILOG-ID` (post-MVP / maintenance origin) or `--from-spec specs/.../spec.md` (greenfield / SpecKit origin). +- **Default** effort: M. + +### 3. Pick origin and effort + +- **Effort heuristic**: XS (≤ half day), S (≤ 1 day), M (1–3 days, default), L (≥ 1 week). +- **Origin precedence**: a single live AILOG → `--from-ailog`; a SpecKit feature spec → `--from-spec`; otherwise omit (the operator can fill `originating_*` fields manually). + +### 4. Run the CLI + +The CLI does the scaffolding — slug derivation, sequential numbering, template substitution, write to `.straymark/charters/NN-slug.md`. The skill's job is to drive it with the right flags. + +```bash +# Greenfield, SpecKit-driven +straymark charter new \ + --title "Workspace foundation for peek MVP" \ + --type M \ + --from-spec specs/001-peek-mvp-foundation/spec.md + +# Post-MVP / maintenance, AILOG-driven +straymark charter new \ + --title "Per-service anomaly thresholds" \ + --type S \ + --from-ailog AILOG-2026-04-28-021 + +# No explicit origin (operator fills frontmatter manually) +straymark charter new --title "Refactor signal pipeline" --type M +``` + +If the title would derive a poor slug, pass `--slug ` explicitly. + +### 5. Hand off to the operator + +After the file is created, the CLI's "Next steps" output already lists what to fill. Surface it verbatim, then remind: + +> Charter status starts at `declared`. Flip to `in-progress` only when execution actually begins. Run `straymark charter drift CHARTER-NN` before `straymark charter close` to catch declared-but-not-modified files (or modified-but-not-declared ones). + +### 6. Report result + +``` +StrayMark: Created CHARTER-NN-slug at .straymark/charters/NN-slug.md + status: declared + effort_estimate: + origin: +``` + +## What this skill does NOT do + +- It does not flip status to `in-progress` or `closed`. Lifecycle transitions are operator decisions. +- It does not run drift or audit. Use `straymark charter drift` and the audit-prompt / audit-execute / audit-review skills for those phases. +- It does not replace AILOGs. Day-to-day work inside the Charter still produces AILOGs; the Charter aggregates them via `originating_ailogs:`. diff --git a/.agent/workflows/devtrail-mcard.md b/.agent/workflows/straymark-mcard.md similarity index 94% rename from .agent/workflows/devtrail-mcard.md rename to .agent/workflows/straymark-mcard.md index 1034c3f..6b5330c 100644 --- a/.agent/workflows/devtrail-mcard.md +++ b/.agent/workflows/straymark-mcard.md @@ -2,7 +2,7 @@ description: Create a Model/System Card (MCARD) document through an interactive step-by-step flow. Guides the user through each section with specific questions and example responses. --- -# DevTrail MCARD Skill +# StrayMark MCARD Skill Create AI Model/System Card documentation through an interactive guided flow. @@ -12,7 +12,7 @@ When invoked, follow these steps: ### 1. Check for Parameters -If the user specified a model name (e.g., `/devtrail-mcard GPT-4o`), use it as the model name and proceed to step 2 asking only for the model type. +If the user specified a model name (e.g., `/straymark-mcard GPT-4o`), use it as the model name and proceed to step 2 asking only for the model type. If no parameter is given, proceed to step 2 asking for both model name and type. @@ -22,7 +22,7 @@ Ask the user: ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail MCARD — Model/System Card ║ +║ StrayMark MCARD — Model/System Card ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ Step 1/7: Model Identity ║ @@ -229,15 +229,15 @@ Based on the gathered information, determine: ### 10. Check Language Configuration -Read `.devtrail/config.yml` to determine language: +Read `.straymark/config.yml` to determine language: ```yaml language: en # or es ``` Use template path based on language: -- `en` (default): `.devtrail/templates/TEMPLATE-MCARD.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-MCARD.md` +- `en` (default): `.straymark/templates/TEMPLATE-MCARD.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-MCARD.md` ### 11. Generate Document ID @@ -248,7 +248,7 @@ Determine the next sequence number: date +%Y-%m-%d # Find existing MCARD documents for today -ls .devtrail/09-ai-models/MCARD-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/09-ai-models/MCARD-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ID format: `MCARD-YYYY-MM-DD-NNN` @@ -259,7 +259,7 @@ Display a summary and ask for confirmation: ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail MCARD — Summary ║ +║ StrayMark MCARD — Summary ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ Model: [model_name] ([model_type]) ║ @@ -272,7 +272,7 @@ Display a summary and ask for confirmation: ║ MCARD-YYYY-MM-DD-NNN-[model-name-slug].md ║ ║ ║ ║ Location: ║ -║ .devtrail/09-ai-models/ ║ +║ .straymark/09-ai-models/ ║ ║ ║ ║ Review required: YES ║ ║ ║ @@ -293,15 +293,15 @@ Wait for user confirmation before proceeding. - `[Model Name]` -> User-provided model name 3. Fill in all sections with the gathered information 4. Set `review_required: true` in the frontmatter -5. Save to `.devtrail/09-ai-models/MCARD-YYYY-MM-DD-NNN-[model-name-slug].md` +5. Save to `.straymark/09-ai-models/MCARD-YYYY-MM-DD-NNN-[model-name-slug].md` ### 14. Report Result After creation, display: ``` -DevTrail MCARD created: - .devtrail/09-ai-models/MCARD-YYYY-MM-DD-NNN-[description].md +StrayMark MCARD created: + .straymark/09-ai-models/MCARD-YYYY-MM-DD-NNN-[description].md Model: [model_name] ([model_type]) Provider: [provider] @@ -312,8 +312,8 @@ DevTrail MCARD created: ## Edge Cases -1. **No `.devtrail/09-ai-models/` directory**: Create it before saving +1. **No `.straymark/09-ai-models/` directory**: Create it before saving 2. **User provides partial information**: Fill known fields, mark unknown fields with `[To be determined]` 3. **User declines confirmation**: Acknowledge and exit gracefully 4. **Third-party model with limited info**: Mark unknown sections with `[Information not publicly available]` and note in limitations -5. **No `.devtrail/config.yml`**: Default to English (`en`) +5. **No `.straymark/config.yml`**: Default to English (`en`) diff --git a/.agent/workflows/devtrail-new.md b/.agent/workflows/straymark-new.md similarity index 69% rename from .agent/workflows/devtrail-new.md rename to .agent/workflows/straymark-new.md index e84b283..38bb92b 100644 --- a/.agent/workflows/devtrail-new.md +++ b/.agent/workflows/straymark-new.md @@ -1,10 +1,10 @@ --- -description: Create DevTrail documentation. Analyzes context to suggest document type or accepts explicit type parameter. Always confirms before creating. +description: Create StrayMark documentation. Analyzes context to suggest document type or accepts explicit type parameter. Always confirms before creating. --- -# DevTrail New Skill +# StrayMark New Skill -Create DevTrail documentation based on recent changes. +Create StrayMark documentation based on recent changes. ## Instructions @@ -12,10 +12,12 @@ When invoked, follow these steps: ### 1. Check for Parameters -If the user specified a document type (e.g., `/devtrail-new ailog`), skip to step 4 using that type. +If the user specified a document type (e.g., `/straymark-new ailog`), skip to step 4 using that type. Valid types: `ailog`, `aidec`, `adr`, `eth`, `req`, `tes`, `inc`, `tde`, `sec`, `mcard`, `sbom`, `dpia` +> **Charter is not a `straymark new` type.** Charters are bounded units of work (filename `NN-slug.md`, sequential prefix) and have their own command. If the user asks for a Charter (`/straymark-new charter`, *"create a Charter"*, *"declare a Charter"*), redirect to the `straymark-charter-new` skill. + ### 2. Analyze Context Gather information about recent changes: @@ -34,7 +36,7 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat git diff --numstat HEAD~1 2>/dev/null || git diff --numstat # Check code complexity (primary method for AILOG trigger) -devtrail analyze --output json 2>/dev/null +straymark analyze --output json 2>/dev/null # If CLI unavailable, fall back to line count heuristic in step 3 ``` @@ -44,14 +46,16 @@ Based on the analysis, suggest a document type: | Pattern | Suggested Type | |---------|---------------| -| Complex code (`devtrail analyze` `above_threshold > 0`; fallback: >20 lines) | AILOG | +| Complex code (`straymark analyze` `above_threshold > 0`; fallback: >20 lines) | AILOG | | Multiple implementation alternatives discussed | AIDEC | | Structural/architectural changes, new modules | ADR | | Files with `auth`, `user`, `privacy`, `gdpr` | ETH (draft) | | Test files (`*.test.*`, `*.spec.*`) | TES | | Bug fixes, hotfixes | INC | -| `TODO`, `FIXME`, `HACK` comments added | TDE | +| `TODO`, `FIXME`, `HACK` comments added | TDE (code-smell trigger) | +| Transversal debt — heritage from prior Charter, applies to multiple modules, requires dedicated Charter, or needs human prioritization | TDE (architectural trigger — distinct from per-Charter `R`; see AGENT-RULES.md §3) | | Requirements or spec files | REQ | +| Multi-session implementation block (>1 day, >5 tasks, multi-phase) | **Charter** — redirect to `straymark-charter-new` (Charters use `straymark charter new`, not `straymark new`) | ### 4. Confirm with User @@ -59,7 +63,7 @@ Based on the analysis, suggest a document type: ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail New ║ +║ StrayMark New ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ 📊 Analysis: ║ @@ -82,15 +86,15 @@ Wait for user confirmation before proceeding. ### 5. Check Language Configuration -Read `.devtrail/config.yml` to determine language: +Read `.straymark/config.yml` to determine language: ```yaml language: en # or es ``` Use template path based on language: -- `en` (default): `.devtrail/templates/TEMPLATE-[TYPE].md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-[TYPE].md` +- `en` (default): `.straymark/templates/TEMPLATE-[TYPE].md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-[TYPE].md` ### 6. Generate Document ID @@ -98,7 +102,7 @@ Determine the next sequence number: ```bash # Find existing documents of this type for today -ls .devtrail/*/[TYPE]-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/*/[TYPE]-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ID format: `[TYPE]-YYYY-MM-DD-NNN` @@ -115,18 +119,18 @@ ID format: `[TYPE]-YYYY-MM-DD-NNN` | Type | Location | |------|----------| -| AILOG | `.devtrail/07-ai-audit/agent-logs/` | -| AIDEC | `.devtrail/07-ai-audit/decisions/` | -| ETH | `.devtrail/07-ai-audit/ethical-reviews/` | -| ADR | `.devtrail/02-design/decisions/` | -| REQ | `.devtrail/01-requirements/` | -| TES | `.devtrail/04-testing/` | -| INC | `.devtrail/05-operations/incidents/` | -| TDE | `.devtrail/06-evolution/technical-debt/` | -| SEC | `.devtrail/08-security/` | -| MCARD | `.devtrail/09-ai-models/` | -| SBOM | `.devtrail/07-ai-audit/` | -| DPIA | `.devtrail/07-ai-audit/ethical-reviews/` | +| AILOG | `.straymark/07-ai-audit/agent-logs/` | +| AIDEC | `.straymark/07-ai-audit/decisions/` | +| ETH | `.straymark/07-ai-audit/ethical-reviews/` | +| ADR | `.straymark/02-design/decisions/` | +| REQ | `.straymark/01-requirements/` | +| TES | `.straymark/04-testing/` | +| INC | `.straymark/05-operations/incidents/` | +| TDE | `.straymark/06-evolution/technical-debt/` | +| SEC | `.straymark/08-security/` | +| MCARD | `.straymark/09-ai-models/` | +| SBOM | `.straymark/07-ai-audit/` | +| DPIA | `.straymark/07-ai-audit/ethical-reviews/` | ### 7.5. Apply Automatic Review Rules @@ -143,8 +147,8 @@ These rules align with the CLI validation rules CROSS-001, CROSS-002, and CROSS- After creation, display: ``` -✅ DevTrail document created: - .devtrail/[path]/[TYPE]-YYYY-MM-DD-NNN-description.md +✅ StrayMark document created: + .straymark/[path]/[TYPE]-YYYY-MM-DD-NNN-description.md Review required: [yes/no] Risk level: [low/medium/high/critical] diff --git a/.agent/workflows/devtrail-sec.md b/.agent/workflows/straymark-sec.md similarity index 89% rename from .agent/workflows/devtrail-sec.md rename to .agent/workflows/straymark-sec.md index fb9a1d5..6627836 100644 --- a/.agent/workflows/devtrail-sec.md +++ b/.agent/workflows/straymark-sec.md @@ -1,14 +1,14 @@ --- -description: Create a DevTrail Security Assessment (SEC) document. Interactive step-by-step flow that gathers scope, threat model methodology, and OWASP ASVS level, then generates a pre-filled SEC document based on code context. Always marks as draft with review_required. +description: Create a StrayMark Security Assessment (SEC) document. Interactive step-by-step flow that gathers scope, threat model methodology, and OWASP ASVS level, then generates a pre-filled SEC document based on code context. Always marks as draft with review_required. --- -# DevTrail Security Assessment Skill +# StrayMark Security Assessment Skill Create a Security Assessment document with threat modeling and OWASP ASVS compliance checks. ## Instructions -When invoked via `/devtrail-sec [component-name]`, follow these steps: +When invoked via `/straymark-sec [component-name]`, follow these steps: ### 1. Gather Assessment Scope @@ -88,7 +88,7 @@ Also scan the codebase for security-relevant patterns in the component area: ``` +------------------------------------------------------------------+ -| DevTrail Security Assessment | +| StrayMark Security Assessment | +------------------------------------------------------------------+ | | | Component: [component-name] | @@ -111,15 +111,15 @@ Wait for user confirmation before proceeding. ### 6. Check Language Configuration -Read `.devtrail/config.yml` to determine language: +Read `.straymark/config.yml` to determine language: ```yaml language: en # or es ``` Use template path based on language: -- `en` (default): `.devtrail/templates/TEMPLATE-SEC.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-SEC.md` +- `en` (default): `.straymark/templates/TEMPLATE-SEC.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-SEC.md` ### 7. Generate Document ID @@ -127,7 +127,7 @@ Determine the next sequence number: ```bash # Find existing SEC documents for today -ls .devtrail/08-security/SEC-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/08-security/SEC-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ID format: `SEC-YYYY-MM-DD-NNN` @@ -152,15 +152,15 @@ ID format: `SEC-YYYY-MM-DD-NNN` - `review_required: true` - `risk_level: high` - `confidence: medium` -5. Save to: `.devtrail/08-security/SEC-YYYY-MM-DD-NNN-[description].md` +5. Save to: `.straymark/08-security/SEC-YYYY-MM-DD-NNN-[description].md` ### 9. Report Result After creation, display: ``` -DevTrail Security Assessment created: - .devtrail/08-security/SEC-YYYY-MM-DD-NNN-description.md +StrayMark Security Assessment created: + .straymark/08-security/SEC-YYYY-MM-DD-NNN-description.md Status: draft Review required: yes @@ -174,7 +174,7 @@ DevTrail Security Assessment created: ## Expected Output Example -For invocation `/devtrail-sec authentication-api`, after the interactive flow selects STRIDE and L1, the generated document would look like: +For invocation `/straymark-sec authentication-api`, after the interactive flow selects STRIDE and L1, the generated document would look like: ```markdown --- @@ -283,7 +283,7 @@ related: [] | Decision | [APPROVED / REJECTED / CONDITIONAL] | | Conditions | [If applicable] | - + ``` ## Edge Cases diff --git a/.agent/workflows/straymark-status.md b/.agent/workflows/straymark-status.md new file mode 100644 index 0000000..9b4cc38 --- /dev/null +++ b/.agent/workflows/straymark-status.md @@ -0,0 +1,123 @@ +--- +description: Show StrayMark documentation status. Use to verify if AI agents properly documented their changes. +--- + +# StrayMark Status Skill + +This skill checks the documentation status of the StrayMark in the current project. + +## Instructions + +When invoked, perform the following checks and display the results: + +### 1. Find Recent StrayMark Documents + +Search for StrayMark documents created or modified in the last hour: + +```bash +# Get documents modified in the last hour +git log --since="1 hour ago" --name-only --pretty=format: -- ".straymark/**/*.md" | sort -u | grep -v "^$" +``` + +If git is not available or the directory is not a git repo, use file modification times. +Check these directories for each document type: + +| Type | Prefix | Directory | +|------|--------|-----------| +| AILOG | `AILOG-` | `.straymark/07-ai-audit/agent-logs/` | +| AIDEC | `AIDEC-` | `.straymark/07-ai-audit/decisions/` | +| ADR | `ADR-` | `.straymark/02-design/decisions/` | +| ETH | `ETH-` | `.straymark/07-ai-audit/ethical-reviews/` | +| REQ | `REQ-` | `.straymark/01-requirements/` | +| TES | `TES-` | `.straymark/04-testing/` | +| INC | `INC-` | `.straymark/05-operations/incidents/` | +| TDE | `TDE-` | `.straymark/06-evolution/technical-debt/` | +| SEC | `SEC-` | `.straymark/08-security/` | +| MCARD | `MCARD-` | `.straymark/09-ai-models/` | +| SBOM | `SBOM-` | `.straymark/07-ai-audit/` | +| DPIA | `DPIA-` | `.straymark/07-ai-audit/ethical-reviews/` | + +Also enumerate **Charters** (bounded units of work — distinct from doc types; see STRAYMARK.md §15): + +```bash +# Charters list with status counts (declared / in-progress / closed) +straymark charter list 2>/dev/null +``` + +If the project has no Charters yet but the work clearly fits the trigger (multi-session implementation block, >5 tasks across phases, audit value), surface that as a gap and recommend the `straymark-charter-new` skill. + +### 2. Find Modified Source Files + +Identify source files that were modified and might need documentation: + +```bash +# Get modified files (staged and unstaged) +git diff --name-only HEAD~1..HEAD 2>/dev/null || git diff --name-only +``` + +Filter to show only files that might need documentation: +- Exclude: `*.md`, `*.json`, `*.yml`, `*.yaml`, `*.lock`, `package-lock.json` +- Include: `*.ts`, `*.js`, `*.tsx`, `*.jsx`, `*.py`, `*.go`, `*.rs`, `*.java`, `*.cs`, `*.rb`, `*.php` + +Run complexity analysis on modified source files: + +```bash +# Analyze complexity of changed files (primary method for AILOG trigger) +straymark analyze --output json 2>/dev/null +# If CLI unavailable, fall back to line count heuristic in step 3 +``` + +### 3. Analyze Documentation Gaps + +For each modified source file, check if there's a corresponding StrayMark document: +- Complex code (`straymark analyze` reports `summary.above_threshold > 0`; **fallback** if CLI unavailable: >20 lines of business logic) should have an AILOG +- Security-related files (auth, crypto, secrets) should have a SEC assessment +- Architecture/structural changes should have an ADR +- AI/ML model changes should have a MCARD +- Dependency changes (`package.json`, `Cargo.toml`, `go.mod`, etc.) should have an SBOM +- Changes involving personal data processing should have a DPIA +- Test files should have a TES record +- Bug fixes or incidents should have an INC record +- Multi-session implementation blocks (>1 day, >5 tasks, multi-phase) should have an open or closed **Charter** at `.straymark/charters/` + +### 4. Display Results + +Format the output as follows: + +``` +StrayMark Status +================================================================================ + +Recent Documents (last hour): + ✅ AILOG-2025-01-27-001-implement-auth.md + ✅ AIDEC-2025-01-27-001-auth-strategy.md + +Modified Files Without Documentation: + ⚠️ src/auth/login.ts (cognitive: 12, threshold: 8) + ⚠️ src/api/users.ts (cognitive: 9, threshold: 8) + +Summary: + Documents created: 2 + Files needing review: 2 + +Use /straymark-new to create documentation for undocumented changes. +``` + +### Symbol Legend + +- ✅ = Documentation exists +- ⚠️ = May need documentation +- ℹ️ = Informational + +### Edge Cases + +1. **No git repository**: Show message explaining git is required for full functionality +2. **No recent documents**: Show "No StrayMark documents created in the last hour" +3. **No modified files**: Show "No source files modified recently" +4. **Empty .straymark directory**: Show warning that StrayMark may not be properly set up + +### Additional Notes + +- This skill is read-only and does not create or modify files +- Run this after completing development tasks to verify documentation compliance +- If files need documentation, remind the user of the StrayMark rules diff --git a/.claude/skills/devtrail-status/SKILL.md b/.claude/skills/devtrail-status/SKILL.md deleted file mode 100644 index c651a70..0000000 --- a/.claude/skills/devtrail-status/SKILL.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -name: devtrail-status -description: Show DevTrail documentation status. Use to verify if AI agents properly documented their changes. -allowed-tools: Read, Glob, Bash(git diff *, git log *, git status *, date *) ---- - -# DevTrail Status Skill - -This skill checks the documentation status of the DevTrail in the current project. - -## Instructions - -When invoked, perform the following checks and display the results: - -### 1. Find Recent DevTrail Documents - -Search for DevTrail documents created or modified in the last hour: - -```bash -# Get documents modified in the last hour -git log --since="1 hour ago" --name-only --pretty=format: -- ".devtrail/**/*.md" | sort -u | grep -v "^$" -``` - -If git is not available or the directory is not a git repo, use file modification times. -Check these directories for each document type: - -| Type | Prefix | Directory | -|------|--------|-----------| -| AILOG | `AILOG-` | `.devtrail/07-ai-audit/agent-logs/` | -| AIDEC | `AIDEC-` | `.devtrail/07-ai-audit/decisions/` | -| ADR | `ADR-` | `.devtrail/04-architecture/decisions/` | -| ETH | `ETH-` | `.devtrail/07-ai-audit/ethical-reviews/` | -| REQ | `REQ-` | `.devtrail/03-requirements/` | -| TES | `TES-` | `.devtrail/05-testing/` | -| INC | `INC-` | `.devtrail/06-operations/incidents/` | -| TDE | `TDE-` | `.devtrail/06-operations/tech-debt/` | -| SEC | `SEC-` | `.devtrail/08-security/` | -| MCARD | `MCARD-` | `.devtrail/09-ai-models/` | -| SBOM | `SBOM-` | `.devtrail/07-ai-audit/` | -| DPIA | `DPIA-` | `.devtrail/07-ai-audit/ethical-reviews/` | - -### 2. Find Modified Source Files - -Identify source files that were modified and might need documentation: - -```bash -# Get modified files (staged and unstaged) -git diff --name-only HEAD~1..HEAD 2>/dev/null || git diff --name-only -``` - -Filter to show only files that might need documentation: -- Exclude: `*.md`, `*.json`, `*.yml`, `*.yaml`, `*.lock`, `package-lock.json` -- Include: `*.ts`, `*.js`, `*.tsx`, `*.jsx`, `*.py`, `*.go`, `*.rs`, `*.java`, `*.cs`, `*.rb`, `*.php` - -### 3. Analyze Documentation Gaps - -For each modified source file, check if there's a corresponding DevTrail document: -- Files with >10 lines of changes in business logic folders should have an AILOG -- Security-related files (auth, crypto, secrets) should have a SEC assessment -- Architecture/structural changes should have an ADR -- AI/ML model changes should have a MCARD -- Dependency changes (`package.json`, `Cargo.toml`, `go.mod`, etc.) should have an SBOM -- Changes involving personal data processing should have a DPIA -- Test files should have a TES record -- Bug fixes or incidents should have an INC record - -### 4. Display Results - -Format the output as follows: - -``` -DevTrail Status -================================================================================ - -Recent Documents (last hour): - [checkmark] AILOG-2025-01-27-001-implement-auth.md - [checkmark] AIDEC-2025-01-27-001-auth-strategy.md - -Modified Files Without Documentation: - [warning] src/auth/login.ts (47 lines changed) - [warning] src/api/users.ts (23 lines changed) - -Summary: - Documents created: 2 - Files needing review: 2 - -Use /devtrail-status after making changes to verify documentation compliance. -``` - -### Symbol Legend - -- `[checkmark]` = Documentation exists (use checkmark symbol) -- `[warning]` = May need documentation (use warning symbol) -- `[info]` = Informational (use info symbol) - -### Edge Cases - -1. **No git repository**: Show message explaining git is required for full functionality -2. **No recent documents**: Show "No DevTrail documents created in the last hour" -3. **No modified files**: Show "No source files modified recently" -4. **Empty .devtrail directory**: Show warning that DevTrail may not be properly set up - -### Additional Notes - -- This skill is read-only and does not create or modify files -- Run this after completing development tasks to verify documentation compliance -- If files need documentation, remind the user of the DevTrail rules diff --git a/.claude/skills/devtrail-adr/SKILL.md b/.claude/skills/straymark-adr/SKILL.md similarity index 86% rename from .claude/skills/devtrail-adr/SKILL.md rename to .claude/skills/straymark-adr/SKILL.md index 4eddd46..411a5d5 100644 --- a/.claude/skills/devtrail-adr/SKILL.md +++ b/.claude/skills/straymark-adr/SKILL.md @@ -1,10 +1,10 @@ --- -name: devtrail-adr +name: straymark-adr description: Create an ADR (Architecture Decision Record) for significant architectural decisions. Requires human review. allowed-tools: Read, Write, Glob, Bash(git diff *, git log *, git status *, date *, wc *) --- -# DevTrail ADR Skill +# StrayMark ADR Skill Create an Architecture Decision Record (ADR) for significant architectural decisions. @@ -24,7 +24,7 @@ date +%Y-%m-%d git diff --stat HEAD~1 2>/dev/null || git diff --stat # Check for related ADRs -ls .devtrail/02-design/decisions/ADR-*.md 2>/dev/null | tail -5 +ls .straymark/02-design/decisions/ADR-*.md 2>/dev/null | tail -5 ``` ### 2. Confirm with User @@ -33,7 +33,7 @@ ls .devtrail/02-design/decisions/ADR-*.md 2>/dev/null | tail -5 ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail ADR ║ +║ StrayMark ADR ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ ⚠️ ADRs require human review after creation. ║ @@ -56,14 +56,14 @@ ls .devtrail/02-design/decisions/ADR-*.md 2>/dev/null | tail -5 ```bash # Count existing ADRs for today -ls .devtrail/02-design/decisions/ADR-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/02-design/decisions/ADR-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ### 4. Check Language and Load Template -Read `.devtrail/config.yml` for language setting: -- `en` (default): `.devtrail/templates/TEMPLATE-ADR.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-ADR.md` +Read `.straymark/config.yml` for language setting: +- `en` (default): `.straymark/templates/TEMPLATE-ADR.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-ADR.md` ### 5. Create Document @@ -88,18 +88,18 @@ Fill template with: - Implementation Plan: High-level steps - Success Metrics: How to validate the decision -Save to: `.devtrail/02-design/decisions/ADR-YYYY-MM-DD-NNN-description.md` +Save to: `.straymark/02-design/decisions/ADR-YYYY-MM-DD-NNN-description.md` ### 6. Report Result ``` ⚠️ ADR created (requires human review): - .devtrail/02-design/decisions/ADR-YYYY-MM-DD-NNN-description.md + .straymark/02-design/decisions/ADR-YYYY-MM-DD-NNN-description.md Status: draft Review Required: YES -DevTrail: Created ADR-YYYY-MM-DD-NNN-description.md (review required) +StrayMark: Created ADR-YYYY-MM-DD-NNN-description.md (review required) ``` ## Examples of Architectural Decisions diff --git a/.claude/skills/devtrail-aidec/SKILL.md b/.claude/skills/straymark-aidec/SKILL.md similarity index 83% rename from .claude/skills/devtrail-aidec/SKILL.md rename to .claude/skills/straymark-aidec/SKILL.md index 0851c4b..e6edfa3 100644 --- a/.claude/skills/devtrail-aidec/SKILL.md +++ b/.claude/skills/straymark-aidec/SKILL.md @@ -1,10 +1,10 @@ --- -name: devtrail-aidec +name: straymark-aidec description: Create an AIDEC (AI Decision) document to record a technical decision with alternatives considered. allowed-tools: Read, Write, Glob, Bash(git diff *, git log *, git status *, date *, wc *) --- -# DevTrail AIDEC Skill +# StrayMark AIDEC Skill Create an AI Decision (AIDEC) document to record technical decisions and the alternatives considered. @@ -28,7 +28,7 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail AIDEC ║ +║ StrayMark AIDEC ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ 📋 AIDEC documents a decision between alternatives. ║ @@ -45,14 +45,14 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat ```bash # Count existing AIDECs for today -ls .devtrail/07-ai-audit/decisions/AIDEC-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/07-ai-audit/decisions/AIDEC-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ### 4. Check Language and Load Template -Read `.devtrail/config.yml` for language setting: -- `en` (default): `.devtrail/templates/TEMPLATE-AIDEC.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-AIDEC.md` +Read `.straymark/config.yml` for language setting: +- `en` (default): `.straymark/templates/TEMPLATE-AIDEC.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-AIDEC.md` ### 5. Create Document @@ -71,15 +71,15 @@ Fill template with: - Decision: Which was chosen and justification - Consequences: Positive, negative, and risks -Save to: `.devtrail/07-ai-audit/decisions/AIDEC-YYYY-MM-DD-NNN-description.md` +Save to: `.straymark/07-ai-audit/decisions/AIDEC-YYYY-MM-DD-NNN-description.md` ### 6. Report Result ``` ✅ AIDEC created: - .devtrail/07-ai-audit/decisions/AIDEC-YYYY-MM-DD-NNN-description.md + .straymark/07-ai-audit/decisions/AIDEC-YYYY-MM-DD-NNN-description.md -DevTrail: Created AIDEC-YYYY-MM-DD-NNN-description.md +StrayMark: Created AIDEC-YYYY-MM-DD-NNN-description.md ``` ## When to Create an AIDEC diff --git a/.claude/skills/devtrail-ailog/SKILL.md b/.claude/skills/straymark-ailog/SKILL.md similarity index 83% rename from .claude/skills/devtrail-ailog/SKILL.md rename to .claude/skills/straymark-ailog/SKILL.md index c0b3324..669507d 100644 --- a/.claude/skills/devtrail-ailog/SKILL.md +++ b/.claude/skills/straymark-ailog/SKILL.md @@ -1,10 +1,10 @@ --- -name: devtrail-ailog +name: straymark-ailog description: Create an AILOG (AI Action Log) document for the current changes. Quick shortcut for the most common document type. allowed-tools: Read, Write, Glob, Bash(git diff *, git log *, git status *, date *, wc *) --- -# DevTrail AILOG Skill +# StrayMark AILOG Skill Quickly create an AI Action Log (AILOG) document for the current changes. @@ -31,7 +31,7 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail AILOG ║ +║ StrayMark AILOG ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ 📊 Changes detected: ║ @@ -49,16 +49,16 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat ```bash # Count existing AILOGs for today -ls .devtrail/07-ai-audit/agent-logs/AILOG-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/07-ai-audit/agent-logs/AILOG-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` Next number = count + 1, formatted as 3 digits (001, 002, etc.) ### 4. Check Language and Load Template -Read `.devtrail/config.yml` for language setting: -- `en` (default): `.devtrail/templates/TEMPLATE-AILOG.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-AILOG.md` +Read `.straymark/config.yml` for language setting: +- `en` (default): `.straymark/templates/TEMPLATE-AILOG.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-AILOG.md` ### 5. Create Document @@ -70,15 +70,15 @@ Fill template with: - `confidence`: based on change complexity - `risk_level`: based on files modified -Save to: `.devtrail/07-ai-audit/agent-logs/AILOG-YYYY-MM-DD-NNN-description.md` +Save to: `.straymark/07-ai-audit/agent-logs/AILOG-YYYY-MM-DD-NNN-description.md` ### 6. Report Result ``` ✅ AILOG created: - .devtrail/07-ai-audit/agent-logs/AILOG-YYYY-MM-DD-NNN-description.md + .straymark/07-ai-audit/agent-logs/AILOG-YYYY-MM-DD-NNN-description.md -DevTrail: Created AILOG-YYYY-MM-DD-NNN-description.md +StrayMark: Created AILOG-YYYY-MM-DD-NNN-description.md ``` ## Risk Level Guidelines diff --git a/.claude/skills/straymark-audit-execute/SKILL.md b/.claude/skills/straymark-audit-execute/SKILL.md new file mode 100644 index 0000000..5c66000 --- /dev/null +++ b/.claude/skills/straymark-audit-execute/SKILL.md @@ -0,0 +1,153 @@ +--- +name: straymark-audit-execute +description: Execute an external audit of a Charter inside an auditor-side CLI (gemini-cli, claude-cli, copilot-cli, codex-cli). Reads the resolved audit prompt from the canonical location, audits with tool use, writes the report. Operator invokes one instance per CLI. +allowed-tools: Read, Write, Glob, Grep, Bash(go vet *, go build *, go test *, cargo check *, cargo clippy *, cargo test --no-run, npm run lint, npm run typecheck, npm test --, pytest --co, mypy *, ruff check *, ls *, find *, wc *, git log *, git diff *, git status *) +argument-hint: "CHARTER-NN (optional — auto-discovers pending prompts)" +--- + +# StrayMark Audit Execute Skill + +Execute an external audit of a Charter inside this CLI session. Read the resolved audit prompt that StrayMark prepared at the canonical location, audit the implementation with tool use (citing `path:line` of files actually opened), and write the report at the canonical location for the audit-review skill to consolidate later. + +## When to invoke + +This skill runs **inside an auditor-side CLI** (gemini-cli, claude-cli, copilot-cli, codex-cli, or any agent runtime configured with read-only access to the adopter's repo). The operator opens the CLI in the repo, then invokes `/straymark-audit-execute `. + +The skill is the second step of the v1 audit cycle: + +1. In the main IDE: operator runs `/straymark-audit-prompt CHARTER-NN` → StrayMark writes `.straymark/audits/CHARTER-NN/audit-prompt.md`. +2. **(this skill)** Operator opens an auditor-side CLI in the repo and runs `/straymark-audit-execute CHARTER-NN`. Repeat in N CLIs (recommended: ≥2 of different model families). +3. When ALL audits commissioned have completed, operator returns to the main IDE and runs `/straymark-audit-review CHARTER-NN`. + +## Instructions + +### 1. Resolve the Charter + +The argument is optional. Two cases: + +**Case A — argument provided** (`/straymark-audit-execute CHARTER-04`): +Use the literal value. Construct the audit dir path: `.straymark/audits/CHARTER-04/`. + +**Case B — argument omitted** (`/straymark-audit-execute`): +Auto-discover pending prompts. Detect this auditor's model identifier (see step 2 for how) and produce its slug. Then: + +```bash +# List all audit prompts that exist +ls .straymark/audits/*/audit-prompt.md 2>/dev/null +``` + +For each found `.straymark/audits//audit-prompt.md`, check whether a report from this model already exists at `.straymark/audits//report-.md`. The set of "pending" prompts is the ones WITHOUT a corresponding report. + +- **Exactly one pending** → proceed with that CHARTER-ID, announcing the choice to the operator. +- **Multiple pending** → list them numerically with their Charter titles (read the title from the resolved prompt's `# Auditoría de Charter — CHARTER-NN` heading) and ask the operator to pick one. +- **None pending** → message: "No pending audit prompts for this model under `.straymark/audits/`. Either the operator has not run `/straymark-audit-prompt` in the main agent yet, or all the prompts already have a report from this model. Verify with the operator." + +### 2. Detect this auditor's model identifier + +Identify the model running this CLI session and produce a filesystem-safe slug. + +The operator will know the canonical model id of the auditor running this skill (for example `claude-sonnet-4-6`, `claude-opus-4-7`, `gemini-2.5-pro`, `gpt-5.3-codex`, `copilot-v1.0.40`). Slug rules: + +- Lowercase ASCII. +- Replace any character that isn't `[a-z0-9-]` with `-`. +- Collapse consecutive dashes to one. +- Trim leading/trailing dashes. + +Examples: + +| Model identifier | Slug | +|---|---| +| `claude-sonnet-4-6` | `claude-sonnet-4-6` | +| `gemini-2.5-pro` | `gemini-2-5-pro` | +| `gpt-5.3-codex` | `gpt-5-3-codex` | +| `copilot-v1.0.40` | `copilot-v1-0-40` | + +If the runtime does not expose the model identifier directly, ask the operator to confirm before proceeding. Do NOT fabricate a slug — collisions or wrong identifiers corrupt the review step. + +### 3. Read the audit prompt + +```bash +cat .straymark/audits//audit-prompt.md +``` + +The prompt is self-contained: it includes the Charter content, originating AILOGs, git diff, and the discipline rules (REGLA ABSOLUTA — SOLO LECTURA, evidence-citation discipline, severity calibration). Read it carefully before auditing. + +### 4. Audit with tool use + +Follow the prompt literally, with these expectations: + +- **Read-only**: never write to project files. The only output you are allowed to produce is the report at the canonical path in step 5. +- **Tool-use evidence**: every finding you record must cite `path:line` of files you actually opened via `Read`, `Grep`, or equivalent. Do not infer behavior from file names alone. +- **Severity calibration**: open the active configuration (factories, env defaults, build tags, deployment scaling) before declaring Critical/High severity. The Etapa 12 example in the prompt is a real case of inflation that the calibration discipline catches. +- **Scope discipline**: only report findings inside the Charter's declared scope. Out-of-scope observations go in their own section, not as defects. + +Track how many `path:line` citations you accumulate — it goes in the report frontmatter as `evidence_citations`. + +### 5. Write the report + +Output path: + +``` +.straymark/audits//report-.md +``` + +If a report at that exact path already exists (re-run on the same Charter with the same model), warn the operator before overwriting. The default is to overwrite — re-runs replace stale reports rather than coexist with them. + +If, by some unusual reason, two distinct sessions of the SAME model audited the same Charter and the operator wants both, append a numeric suffix manually: `report--2.md`. + +The report frontmatter MUST conform to `audit-output.schema.v0.json`: + +```yaml +--- +audit_role: auditor +auditor: # e.g., claude-sonnet-4-6 +charter_id: +git_range: "" +prompt_used: audit-prompt.md +audited_at: +findings_total: +findings_by_category: + hallucination: + implementation_gap: + real_debt: + false_positive: +evidence_citations: # how many path:line citations the body contains +audit_quality: high | medium | low +--- + +# (body following the format declared in the prompt's "Formato de salida" section) +``` + +### 6. Notify the operator — with the wait warning + +After writing the report, print this message verbatim (substituting ``, ``, and the finding count): + +``` +Audit complete for (this auditor: ). + + Report: .straymark/audits//report-.md + Findings: total () + +IMPORTANT: do NOT return to the main agent for /straymark-audit-review yet +unless ALL audits you commissioned have completed. + +If you opened other auditor CLIs (gemini-cli, copilot-cli, codex-cli, ...) +and have not yet seen their /straymark-audit-execute finish, wait for them. +Invoking /straymark-audit-review with incomplete reports produces a partial +consolidated analysis that you will have to discard or re-run — costing +you the audit cycle. + +When and only when ALL audits you commissioned are complete, return to +your main IDE and run: + + /straymark-audit-review +``` + +This wait warning matters: an operator with three CLIs open in parallel can be tempted to invoke review as soon as the first audit finishes. The review skill iterates whatever reports are present at the time it runs; it cannot wait for additional reports to arrive. + +## Notes + +- **No HTTP API calls.** This skill runs inside an auditor CLI that the operator chose; that CLI handles all model invocation, API keys, and rate limits. StrayMark orchestrates prompt resolution and report shape — nothing else. +- **Re-runs**: if you invoke this skill on a Charter whose report from this model already exists, the existing one is overwritten. The previous report is lost — if you wanted to keep it, copy it manually before re-running. +- **Multiple Charters in the same CLI session**: invoke the skill once per Charter. Reports do not collide because the filename is keyed on Charter id + model slug. +- **Heterogeneity inter-family**: the skill does not enforce that the operator uses different model families across the N audit-execute invocations. The recommendation is in the audit prompt itself and in `AGENT-RULES.md` §12; trust the operator. diff --git a/.claude/skills/straymark-audit-prompt/SKILL.md b/.claude/skills/straymark-audit-prompt/SKILL.md new file mode 100644 index 0000000..467983f --- /dev/null +++ b/.claude/skills/straymark-audit-prompt/SKILL.md @@ -0,0 +1,85 @@ +--- +name: straymark-audit-prompt +description: Generate the unified audit prompt for a Charter at the canonical filesystem location. The operator then opens N auditor-side CLIs (gemini-cli, claude-cli, copilot-cli, etc.) and invokes /straymark-audit-execute in each — no copy/paste. Counterpart of /straymark-audit-review. +allowed-tools: Read, Bash(straymark charter audit *, straymark charter status *, ls *) +--- + +# StrayMark Audit Prompt Skill + +Generate the unified audit prompt for a Charter and write it to the canonical filesystem location. The operator then opens auditor-side CLIs in the same repo and invokes `/straymark-audit-execute` — the audit prompt is read directly from disk by each auditor; the operator never copies/pastes. + +## When to invoke + +Use this skill when the developer agreed to run an external audit at the Charter checkpoint (see `.straymark/00-governance/AGENT-RULES.md` § Audit checkpoint). + +The Charter should be in `in-progress` or `declared` status — auditing closed Charters is allowed but atypical (warn the operator and proceed only on confirmation). + +## Instructions + +### 1. Resolve the Charter + +Argument: a Charter identifier (`CHARTER-04`, `04`, or full id with slug). + +```bash +straymark charter status +``` + +Verify the Charter exists and capture its `status`. If `status: closed`, surface a one-line warning to the operator and ask whether to proceed. + +### 2. Generate the unified audit prompt + +```bash +straymark charter audit --prepare +``` + +The CLI writes the resolved prompt to: + +``` +.straymark/audits//audit-prompt.md +``` + +The prompt is self-contained: it embeds the Charter content, the originating AILOGs, the git diff over the resolved range (default `origin/main..HEAD`, falls back to `HEAD~1..HEAD` if no upstream is reachable), and the discipline rules (REGLA ABSOLUTA — SOLO LECTURA, evidence-citation, severity calibration). The prompt template lifts the seven universal sections from Sentinel's pre-StrayMark audit skill and parameterizes the project-specific hardcodes. + +The CLI does NOT invoke any LLM. It only resolves placeholders. + +### 3. Notify the operator + +After the CLI succeeds, print this guidance verbatim (substituting ``): + +``` +Audit prompt prepared for . + + Location: .straymark/audits//audit-prompt.md + (informational — you don't need to copy this path anywhere) + +Next steps: + + 1. Open one or more auditor-side CLIs (gemini-cli, claude-cli, + copilot-cli, codex-cli — whatever you have) in this repo. Each + CLI session uses its own model; recommendation is at least 2 + auditors of DIFFERENT model families, so cross-family blind + spots become signal when their findings converge. + + 2. In each auditor CLI, invoke: + + /straymark-audit-execute + + The skill is already installed (straymark init copies it to all + three platform locations). It reads the prompt from disk + automatically — you do not need to copy/paste anything. + + 3. When and only when ALL audits you commissioned have completed, + return to this main agent and run: + + /straymark-audit-review + + Reviewing with incomplete reports gives you a partial consolidated + analysis that you will have to discard or re-run. +``` + +## Notes + +- This skill is **orchestration-only**. It does NOT invoke LLM APIs, decide which models the operator uses, or wait for responses. It runs the CLI's `--prepare`, points the operator at the next-step skill, and exits. +- Re-running the skill on the same Charter regenerates the prompt at the same path. It does NOT touch operator-saved reports under `.straymark/audits//report-*.md`. +- Heterogeneity inter-family is recommended but not enforced in v0; the operator decides the model pairing across the N CLIs they open. +- For the rationale on cross-family auditors, see `dist/.straymark/audit-prompts/audit-prompt.md` § Tu rol or `Propuesta/straymark-cli-roadmap.md` §5.2 in the upstream repo. diff --git a/.claude/skills/straymark-audit-review/SKILL.md b/.claude/skills/straymark-audit-review/SKILL.md new file mode 100644 index 0000000..f95c581 --- /dev/null +++ b/.claude/skills/straymark-audit-review/SKILL.md @@ -0,0 +1,253 @@ +--- +name: straymark-audit-review +description: Consolidate N external auditor reports into a critical review document with verdicts, remediation plan, and auditor ratings. Then merge the external_audit YAML block into the Charter telemetry. Counterpart of /straymark-audit-prompt and /straymark-audit-execute. +allowed-tools: Read, Write, Glob, Grep, Bash(straymark charter audit *, straymark charter status *, ls *, git diff *, git log *) +--- + +# StrayMark Audit Review Skill + +Critically evaluate the N external auditor reports for a Charter, cross-reference each finding against the actual source code, and produce a consolidated `review.md` with verdicts, a prioritized remediation plan, and per-auditor ratings. Then merge the `external_audit` YAML block into the Charter telemetry. + +This is the third and final step of the v1 audit cycle, and it is where the substance lives — the calibrator role (definitional reconciliation across heterogeneous auditor verdicts) is now performed by the main agent inline, replacing the v0 paste-based calibrator-reconciler prompt. + +## When to invoke + +After the operator has commissioned the audits in N auditor-side CLIs (each running `/straymark-audit-execute `) and **all of them have completed**. The operator returns to the main IDE and invokes: + +``` +/straymark-audit-review +``` + +If only some audits have completed, **do not proceed** — invoking the skill with incomplete reports produces a partial consolidated analysis. Verify with the operator that all the CLIs they opened have finished writing their reports under `.straymark/audits//report-*.md`. + +## Instructions + +### 1. Resolve the Charter and verify report set + +Argument: a Charter identifier. + +```bash +ls -la .straymark/audits// +``` + +Confirm: + +- `audit-prompt.md` exists (the prepared prompt the auditors read). +- `report-*.md` files exist (one per auditor that completed). At least 2 reports are recommended for cross-family heterogeneity to deliver signal; warn (do not block) if only 1 report is present. +- Match each `report-.md` filename against the model identifier in its frontmatter (`auditor:` field) to confirm consistency. Discrepancies are surfaced to the operator. + +If only the prompt is present and no reports exist, instruct the operator to run `/straymark-audit-execute` in the auditor CLIs first. + +### 2. Read all auditor reports + extract finding master list + +For each `.straymark/audits//report-*.md`: + +- Validate the frontmatter against `audit-output.schema.v0.json` (the CLI does this in step 6, but a soft check here gives an earlier and more readable error if any report is malformed). +- Extract: model identifier, total findings, findings by category, evidence_citations count, audit_quality. +- Parse the body for finding entries (typically `## Findings` → `### F1 — title — category` blocks with `Where:`, `What I observed:`, `Why I'm flagging it:`). + +Build a **master finding list** — every unique claim across all auditors, deduplicated when two auditors clearly describe the same thing. + +### 3. Verify every finding against actual code + +This is the substantive step. For EACH finding in the master list: + +**Launch Explore agents in parallel** (up to 3 at a time) to verify findings. Group findings by the file they reference and send related findings to the same agent. + +For each finding, the verification answers four questions: + +1. **Does the code actually have this problem?** Read the cited `path:line`. Is the claim accurate? +2. **Is it in scope?** Does the finding affect a task or file declared in the Charter? If it's outside the Charter's scope, classify as `MISATTRIBUTED`. +3. **What's the real severity given the CURRENT configuration?** Check active driver, feature flags, build tags, DB role, deployment scope (the calibration discipline from the audit prompt). The Etapa 12 example in the prompt is a real case of inflation that careful calibration catches. +4. **Is it a duplicate?** Does another auditor report the same finding differently? + +#### Verdict classification + +Each finding gets one of these verdicts: + +- **VALID** — Real problem, in scope, correctly described, correctly severized. +- **PARTIALLY VALID** — Real observation but wrong severity, missing nuance, or triggers only under a config not active in main. Include the reclassification. +- **MISATTRIBUTED** — Real observation but belongs to a different Charter or scope unit. +- **FALSE POSITIVE** — Claim is factually incorrect (file exists, code works as expected, the assumed driver isn't active, etc.). +- **DUPLICATE** — Same finding reported by another auditor (reference the original). + +#### Severity reclassification + +When the auditor's severity does not match the active configuration: + +- **Inflation** (auditor says Critical/High, code confirms only conditional): downgrade to Medium with explicit note on what config would activate it, OR move to "post-Charter / no bloqueante" if the trigger is a component not yet implemented. +- **Deflation** (auditor says Low/None, code shows a real trigger in current config): upgrade with evidence from the code path that activates it. +- **Correct inflation** (auditor says Critical and config confirms it): keep. + +An auditor that consistently inflates or deflates loses points in the auditor rating (step 5). + +### 4. Identify findings the auditors missed + +Based on your code exploration, check whether there are problems the auditors did NOT find. Focus on: + +- Security: SQL queries missing ownership filters, missing transaction boundaries, secrets in logs. +- Logic: input parameters ignored, dead code paths, unreachable branches. +- Consistency: naming mismatches between layers (model vs handler vs API). + +Mark these as "Missed by all auditors" in the remediation plan. + +### 5. Build the consolidated review.md + +Write the consolidated analysis to `.straymark/audits//review.md` with this structure (six sections, lifted from Sentinel's pre-StrayMark audit-review skill): + +```markdown +--- +audit_role: calibrator-reconciler +calibrator: +charter_id: +git_range: "" +prompt_used: ../audit-prompt.md +calibrated_at: +auditors_reconciled: + - report-.md + - report-.md + - ... +findings_consolidated: +findings_by_status: + agreed: + disputed: + unique_: + unique_: + rejected: +--- + +# Consolidated audit review — + +**Reviewer:** +**Date:** +**Confidence:** [High | Medium] + +## 1. Executive summary + +[2-3 paragraphs. Total findings count, scope confusion if any, most critical bug, +overall verdict on the Charter's implementation.] + +## 2. Scope definition + +[Table of Charter tasks, the closing criterion, and what IS vs IS NOT in scope +of this Charter. The auditors' findings are evaluated against THIS scope.] + +## 3. Per-auditor evaluation + +### 3.1 (model: ) + +| # | Finding | Reported severity | Verdict | Justification | +|---|---------|-------------------|---------|---------------| + +**Summary:** [2-3 sentences on this auditor's overall performance.] + +### 3.2 ... (same shape) + +## 4. Remediation plan — VALID and PARTIALLY VALID findings + +### P0 — Security +- **Files:** `path:line` +- **Problem:** [description with code evidence] +- **Remediation:** [specific approach] +- **Complexity:** [Low / Medium / High] +- **Detected by:** [auditor slug(s), or "Missed by all auditors" if you found it] + +### P1 — Integrity +[Same shape] + +### P2 — Consistency +[Same shape] + +### P3 — Robustness +[Same shape] + +### P4 — Documentation +[Same shape] + +## 5. Discarded findings — misattributions and false positives + +| Finding | Type | Charter / area | Auditor | +|---------|------|----------------|---------| + +## 6. Auditor ratings + +Score each auditor 1-10 across four criteria with weights: + +| Auditor | Scope precision (25%) | Technical depth (25%) | Bug detection (30%) | False positive rate (20%) | **Overall** | +|---------|:-:|:-:|:-:|:-:|:-:| +| | /10 | /10 | /10 | /10 | **/10** | +| ... + +### Justifications + +** — /10**: [2-3 sentences on what this auditor did well and where they slipped.] + +## 7. Conclusion + +[State of the Charter — clean / partial / deviated. Critical findings count. +Key remediation items the operator should address before close. +Recommended next step.] +``` + +### 6. Validate + emit external_audit YAML + +Run the CLI's merge step to validate all reports against the schema and emit the YAML block (combined with `--merge-into` if the operator's Charter telemetry already exists): + +**Branch A — telemetry exists** (operator already ran `straymark charter close` for this Charter, perhaps without audit, and is now adding audit findings retroactively): + +```bash +straymark charter audit --merge-reports \ + --merge-into .straymark/charters/.telemetry.yaml +``` + +The CLI appends the `external_audit:` array to the telemetry YAML. The CLI v1 deliberately rejects re-audit (file already has `external_audit:`) — if that fires, surface the message to the operator. Manual append is the fallback. + +**Branch B — telemetry does NOT exist** (the typical case: operator audits BEFORE closing): + +```bash +straymark charter audit --merge-reports +``` + +The YAML block prints to stdout. Capture it and write it to `.straymark/audits//external-audit-pending.yaml` so the operator can paste it into the telemetry when running `straymark charter close `. Tell the operator: "When you run `straymark charter close `, paste the `external_audit:` block from `.straymark/audits//external-audit-pending.yaml` when prompted." + +### 7. Notify the operator with a summary + +``` +Consolidated audit review complete for . + + Auditors reconciled: + Findings reported: + Findings VALID: (%) + False positives: + Misattributions: + Missed by all (you): + + Remediation plan: + P0 (Security): + P1 (Integrity): + P2-P4 (Other): + + Auditor ratings: + : /10 + : /10 + ... + + Documents written: + .straymark/audits//review.md + [either: .straymark/charters/.telemetry.yaml (merged)] + [or: .straymark/audits//external-audit-pending.yaml] + +Run `git diff` to review the changes before commit. +``` + +## Notes + +- **The calibrator role is in-conversation, not in a paste-based prompt.** v0 had a `calibrator-reconciler.md` template that the operator pasted into a separate model. v1 eliminates that round-trip — the main agent (this conversation) has filesystem access and can verify findings against code, which is what makes the consolidated review substantive instead of mechanical. +- **Heterogeneity inter-family is for the auditor pair, not the calibrator.** The calibrator (this skill, running in the main agent) may be of any family — even the same family as one of the auditors — because its task is definitional (apply the schema to already-produced verdicts), not discovery. +- **The review.md is the human-readable delivery; the YAML block is the machine-readable input to telemetry.** Both coexist by design. The operator reads `review.md`; `straymark metrics` and the Phase 2 telemetry aggregation read the YAML. +- **Re-running the skill** overwrites `review.md`. If the operator wants to keep the previous review (e.g., after a re-audit cycle), instruct them to copy it manually before re-running. +- **No HTTP API calls.** The skill runs the CLI's `--merge-reports` (which validates schemas and emits YAML), invokes Explore agents internally for code verification (which run in the main agent's context, not external APIs), and writes markdown. StrayMark does not invoke LLM APIs at any point. + +## Credit + +The six-section structure of `review.md` and the verdict vocabulary (VALID / PARTIALLY VALID / MISATTRIBUTED / FALSE POSITIVE / DUPLICATE) are lifted from the `audit-review/SKILL.md` skill mature pre-StrayMark in Sentinel, contributed via [issue #102](https://github.com/StrangeDaysTech/straymark/issues/102) by José Villaseñor Montfort (StrangeDaysTech). The four-criterion weighted auditor rating (Scope precision 25% / Technical depth 25% / Bug detection 30% / False positive rate 20%) is the same. Project-specific hardcodes parameterized. diff --git a/.claude/skills/straymark-charter-new/SKILL.md b/.claude/skills/straymark-charter-new/SKILL.md new file mode 100644 index 0000000..1bc9281 --- /dev/null +++ b/.claude/skills/straymark-charter-new/SKILL.md @@ -0,0 +1,114 @@ +--- +name: straymark-charter-new +description: Scaffold a Charter — StrayMark's bounded unit of work that pairs declarative ex-ante scope with telemetry ex-post. Use when starting a multi-session implementation block (>1 day, >5 tasks, multi-phase). +allowed-tools: Read, Write, Glob, Bash(git diff *, git log *, git status *, date *, wc *, ls *, straymark charter *) +--- + +# StrayMark Charter Scaffold Skill + +Declare a Charter at the start of a bounded, auditable unit of work — *not* every change. Charters wrap multi-session work that warrants a stable scope contract you can drift-check at close. They are conceptually distinct from the 12+4 governance document types (AILOG, ADR, AIDEC, …): Charters live at `.straymark/charters/NN-slug.md` and use a sequential prefix instead of a date prefix. + +> See `STRAYMARK.md §15` and `.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md` for the lifecycle and the SpecKit ↔ Charter bridge. + +## When to use this skill + +Trigger on any of: + +- Multi-session implementation block (>1 day, >5 tasks across phases). +- Work that warrants external audit at completion. +- A SpecKit feature has reached `tasks.md` and the operator wants a stable scope contract before `/speckit-implement`. +- The user asks to "declare", "open", or "start" a Charter. + +If the work is a single-session change → use `/straymark-ailog` instead. + +## Instructions + +### 1. Gather context + +```bash +# Sequential number of the Charter being created +straymark charter list 2>/dev/null | tail -5 || true + +# Surrounding spec / AILOG context — Charters frequently originate from one +ls specs/*/spec.md 2>/dev/null | head -5 +ls .straymark/07-ai-audit/agent-logs/AILOG-*.md 2>/dev/null | tail -5 +``` + +### 2. Confirm with user + +``` +╔══════════════════════════════════════════════════════════════════╗ +║ StrayMark Charter — declare a bounded unit of work ║ +╠══════════════════════════════════════════════════════════════════╣ +║ ║ +║ 📋 A Charter pairs declarative scope (ex-ante) with telemetry ║ +║ (ex-post). Lifecycle: declared → in-progress → closed. ║ +║ ║ +║ Required: ║ +║ 1. Title (one line) ║ +║ 2. Effort estimate: XS | S | M | L ║ +║ ║ +║ One of (optional but encouraged): ║ +║ 3a. --from-ailog AILOG-ID (post-MVP / maintenance origin) ║ +║ 3b. --from-spec specs/.../spec.md (greenfield / SpecKit origin) ║ +║ ║ +║ Default effort: M. ║ +║ ║ +╚══════════════════════════════════════════════════════════════════╝ +``` + +### 3. Pick origin and effort + +- **Effort heuristic**: XS (≤ half day), S (≤ 1 day), M (1–3 days, default), L (≥ 1 week). +- **Origin precedence**: a single live AILOG → `--from-ailog`; a SpecKit feature spec → `--from-spec`; otherwise omit (the operator can fill `originating_*` fields manually). + +### 4. Run the CLI + +The CLI does the scaffolding — slug derivation, sequential numbering, template substitution, write to `.straymark/charters/NN-slug.md`. The skill's job is to drive it with the right flags. + +```bash +# Greenfield, SpecKit-driven +straymark charter new \ + --title "Workspace foundation for peek MVP" \ + --type M \ + --from-spec specs/001-peek-mvp-foundation/spec.md + +# Post-MVP / maintenance, AILOG-driven +straymark charter new \ + --title "Per-service anomaly thresholds" \ + --type S \ + --from-ailog AILOG-2026-04-28-021 + +# No explicit origin (operator fills frontmatter manually) +straymark charter new --title "Refactor signal pipeline" --type M +``` + +If the title would derive a poor slug, pass `--slug ` explicitly. + +### 5. Hand off to the operator + +After the file is created, the CLI's "Next steps" output already lists what to fill. Surface it verbatim, then add: + +> **Reminder**: Charter status starts at `declared`. Flip to `in-progress` only when execution actually begins. Run `straymark charter drift CHARTER-NN` before `straymark charter close` to catch declared-but-not-modified files (or modified-but-not-declared ones). + +### 6. Report result + +``` +✓ Charter declared: + .straymark/charters/NN-slug.md + + charter_id: CHARTER-NN-slug + status: declared + effort_estimate: + origin: + +StrayMark: Created CHARTER-NN-slug +``` + +## What this skill does NOT do + +- **It does not flip status to `in-progress` or `closed`.** Lifecycle transitions are operator decisions; pumps the operator through `straymark charter close` (or manual frontmatter edit for `in-progress`). +- **It does not run drift or audit.** Use `straymark charter drift` and `/straymark-audit-prompt` / `/straymark-audit-execute` / `/straymark-audit-review` for those phases. +- **It does not replace AILOGs.** Day-to-day work inside the Charter still produces AILOGs; the Charter aggregates them via `originating_ailogs:`. + +> **Terminal compatibility**: If the terminal does not support box-drawing characters (Unicode), use plain-text formatting with dashes and pipes instead (e.g., `+--+` instead of `╔══╗`). diff --git a/.claude/skills/devtrail-mcard/SKILL.md b/.claude/skills/straymark-mcard/SKILL.md similarity index 94% rename from .claude/skills/devtrail-mcard/SKILL.md rename to .claude/skills/straymark-mcard/SKILL.md index 76e36c8..0b026b4 100644 --- a/.claude/skills/devtrail-mcard/SKILL.md +++ b/.claude/skills/straymark-mcard/SKILL.md @@ -1,10 +1,10 @@ --- -name: devtrail-mcard +name: straymark-mcard description: Create a Model/System Card (MCARD) document through an interactive step-by-step flow. Guides the user through each section with specific questions and example responses. allowed-tools: Read, Write, Glob, Bash(git status *, git log *, git diff *, date *, wc *) --- -# DevTrail MCARD Skill +# StrayMark MCARD Skill Create AI Model/System Card documentation through an interactive guided flow. @@ -14,7 +14,7 @@ When invoked, follow these steps: ### 1. Check for Parameters -If the user specified a model name (e.g., `/devtrail-mcard GPT-4o`), use it as the model name and proceed to step 2 asking only for the model type. +If the user specified a model name (e.g., `/straymark-mcard GPT-4o`), use it as the model name and proceed to step 2 asking only for the model type. If no parameter is given, proceed to step 2 asking for both model name and type. @@ -24,7 +24,7 @@ Ask the user: ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail MCARD — Model/System Card ║ +║ StrayMark MCARD — Model/System Card ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ Step 1/7: Model Identity ║ @@ -231,15 +231,15 @@ Based on the gathered information, determine: ### 10. Check Language Configuration -Read `.devtrail/config.yml` to determine language: +Read `.straymark/config.yml` to determine language: ```yaml language: en # or es ``` Use template path based on language: -- `en` (default): `.devtrail/templates/TEMPLATE-MCARD.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-MCARD.md` +- `en` (default): `.straymark/templates/TEMPLATE-MCARD.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-MCARD.md` ### 11. Generate Document ID @@ -250,7 +250,7 @@ Determine the next sequence number: date +%Y-%m-%d # Find existing MCARD documents for today -ls .devtrail/09-ai-models/MCARD-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/09-ai-models/MCARD-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ID format: `MCARD-YYYY-MM-DD-NNN` @@ -261,7 +261,7 @@ Display a summary and ask for confirmation: ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail MCARD — Summary ║ +║ StrayMark MCARD — Summary ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ Model: [model_name] ([model_type]) ║ @@ -274,7 +274,7 @@ Display a summary and ask for confirmation: ║ MCARD-YYYY-MM-DD-NNN-[model-name-slug].md ║ ║ ║ ║ Location: ║ -║ .devtrail/09-ai-models/ ║ +║ .straymark/09-ai-models/ ║ ║ ║ ║ Review required: YES ║ ║ ║ @@ -295,15 +295,15 @@ Wait for user confirmation before proceeding. - `[Model Name]` -> User-provided model name 3. Fill in all sections with the gathered information 4. Set `review_required: true` in the frontmatter -5. Save to `.devtrail/09-ai-models/MCARD-YYYY-MM-DD-NNN-[model-name-slug].md` +5. Save to `.straymark/09-ai-models/MCARD-YYYY-MM-DD-NNN-[model-name-slug].md` ### 14. Report Result After creation, display: ``` -DevTrail MCARD created: - .devtrail/09-ai-models/MCARD-YYYY-MM-DD-NNN-[description].md +StrayMark MCARD created: + .straymark/09-ai-models/MCARD-YYYY-MM-DD-NNN-[description].md Model: [model_name] ([model_type]) Provider: [provider] @@ -314,10 +314,10 @@ DevTrail MCARD created: ## Edge Cases -1. **No `.devtrail/09-ai-models/` directory**: Create it before saving +1. **No `.straymark/09-ai-models/` directory**: Create it before saving 2. **User provides partial information**: Fill known fields, mark unknown fields with `[To be determined]` 3. **User declines confirmation**: Acknowledge and exit gracefully 4. **Third-party model with limited info**: Mark unknown sections with `[Information not publicly available]` and note in limitations -5. **No `.devtrail/config.yml`**: Default to English (`en`) +5. **No `.straymark/config.yml`**: Default to English (`en`) > **Terminal compatibility**: If the terminal does not support box-drawing characters (Unicode), use plain-text formatting with dashes and pipes instead (e.g., `+--+` instead of `╔══╗`). diff --git a/.claude/skills/devtrail-new/SKILL.md b/.claude/skills/straymark-new/SKILL.md similarity index 70% rename from .claude/skills/devtrail-new/SKILL.md rename to .claude/skills/straymark-new/SKILL.md index 7e56c32..155561f 100644 --- a/.claude/skills/devtrail-new/SKILL.md +++ b/.claude/skills/straymark-new/SKILL.md @@ -1,12 +1,12 @@ --- -name: devtrail-new -description: Create DevTrail documentation. Analyzes context to suggest document type or accepts explicit type parameter. Always confirms before creating. -allowed-tools: Read, Write, Glob, Bash(git diff *, git log *, git status *, date *, wc *, devtrail analyze *) +name: straymark-new +description: Create StrayMark documentation. Analyzes context to suggest document type or accepts explicit type parameter. Always confirms before creating. +allowed-tools: Read, Write, Glob, Bash(git diff *, git log *, git status *, date *, wc *, straymark analyze *) --- -# DevTrail New Skill +# StrayMark New Skill -Create DevTrail documentation based on recent changes. +Create StrayMark documentation based on recent changes. ## Instructions @@ -14,10 +14,12 @@ When invoked, follow these steps: ### 1. Check for Parameters -If the user specified a document type (e.g., `/devtrail-new ailog`), skip to step 4 using that type. +If the user specified a document type (e.g., `/straymark-new ailog`), skip to step 4 using that type. Valid types: `ailog`, `aidec`, `adr`, `eth`, `req`, `tes`, `inc`, `tde`, `sec`, `mcard`, `sbom`, `dpia` +> **Charter is not a `straymark new` type.** Charters are bounded units of work (filename `NN-slug.md`, sequential prefix) and have their own command. If the user asks for a Charter (`/straymark-new charter`, *"create a Charter"*, *"declare a Charter"*), redirect to `/straymark-charter-new`. + ### 2. Analyze Context Gather information about recent changes: @@ -36,7 +38,7 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat git diff --numstat HEAD~1 2>/dev/null || git diff --numstat # Check code complexity (primary method for AILOG trigger) -devtrail analyze --output json 2>/dev/null +straymark analyze --output json 2>/dev/null # If CLI unavailable, fall back to line count heuristic in step 3 ``` @@ -46,14 +48,16 @@ Based on the analysis, suggest a document type: | Pattern | Suggested Type | |---------|---------------| -| Complex code (`devtrail analyze` `above_threshold > 0`; fallback: >20 lines) | AILOG | +| Complex code (`straymark analyze` `above_threshold > 0`; fallback: >20 lines) | AILOG | | Multiple implementation alternatives discussed | AIDEC | | Structural/architectural changes, new modules | ADR | | Files with `auth`, `user`, `privacy`, `gdpr` | ETH (draft) | | Test files (`*.test.*`, `*.spec.*`) | TES | | Bug fixes, hotfixes | INC | -| `TODO`, `FIXME`, `HACK` comments added | TDE | +| `TODO`, `FIXME`, `HACK` comments added | TDE (code-smell trigger) | +| Transversal debt — heritage from prior Charter, applies to multiple modules, requires dedicated Charter, or needs human prioritization | TDE (architectural trigger — distinct from per-Charter `R`; see AGENT-RULES.md §3) | | Requirements or spec files | REQ | +| Multi-session implementation block (>1 day, >5 tasks, multi-phase) | **Charter** — redirect to `/straymark-charter-new` (Charters use the `straymark charter new` CLI, not `straymark new`) | ### 4. Confirm with User @@ -61,7 +65,7 @@ Based on the analysis, suggest a document type: ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail New ║ +║ StrayMark New ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ 📊 Analysis: ║ @@ -84,15 +88,15 @@ Wait for user confirmation before proceeding. ### 5. Check Language Configuration -Read `.devtrail/config.yml` to determine language: +Read `.straymark/config.yml` to determine language: ```yaml language: en # or es ``` Use template path based on language: -- `en` (default): `.devtrail/templates/TEMPLATE-[TYPE].md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-[TYPE].md` +- `en` (default): `.straymark/templates/TEMPLATE-[TYPE].md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-[TYPE].md` ### 6. Generate Document ID @@ -100,7 +104,7 @@ Determine the next sequence number: ```bash # Find existing documents of this type for today -ls .devtrail/*/[TYPE]-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/*/[TYPE]-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ID format: `[TYPE]-YYYY-MM-DD-NNN` @@ -117,18 +121,18 @@ ID format: `[TYPE]-YYYY-MM-DD-NNN` | Type | Location | |------|----------| -| AILOG | `.devtrail/07-ai-audit/agent-logs/` | -| AIDEC | `.devtrail/07-ai-audit/decisions/` | -| ETH | `.devtrail/07-ai-audit/ethical-reviews/` | -| ADR | `.devtrail/02-design/decisions/` | -| REQ | `.devtrail/01-requirements/` | -| TES | `.devtrail/04-testing/` | -| INC | `.devtrail/05-operations/incidents/` | -| TDE | `.devtrail/06-evolution/technical-debt/` | -| SEC | `.devtrail/08-security/` | -| MCARD | `.devtrail/09-ai-models/` | -| SBOM | `.devtrail/07-ai-audit/` | -| DPIA | `.devtrail/07-ai-audit/ethical-reviews/` | +| AILOG | `.straymark/07-ai-audit/agent-logs/` | +| AIDEC | `.straymark/07-ai-audit/decisions/` | +| ETH | `.straymark/07-ai-audit/ethical-reviews/` | +| ADR | `.straymark/02-design/decisions/` | +| REQ | `.straymark/01-requirements/` | +| TES | `.straymark/04-testing/` | +| INC | `.straymark/05-operations/incidents/` | +| TDE | `.straymark/06-evolution/technical-debt/` | +| SEC | `.straymark/08-security/` | +| MCARD | `.straymark/09-ai-models/` | +| SBOM | `.straymark/07-ai-audit/` | +| DPIA | `.straymark/07-ai-audit/ethical-reviews/` | ### 7.5. Apply Automatic Review Rules @@ -145,8 +149,8 @@ These rules align with the CLI validation rules CROSS-001, CROSS-002, and CROSS- After creation, display: ``` -✅ DevTrail document created: - .devtrail/[path]/[TYPE]-YYYY-MM-DD-NNN-description.md +✅ StrayMark document created: + .straymark/[path]/[TYPE]-YYYY-MM-DD-NNN-description.md Review required: [yes/no] Risk level: [low/medium/high/critical] diff --git a/.claude/skills/devtrail-sec/SKILL.md b/.claude/skills/straymark-sec/SKILL.md similarity index 89% rename from .claude/skills/devtrail-sec/SKILL.md rename to .claude/skills/straymark-sec/SKILL.md index 280efa0..071e3b7 100644 --- a/.claude/skills/devtrail-sec/SKILL.md +++ b/.claude/skills/straymark-sec/SKILL.md @@ -1,16 +1,16 @@ --- -name: devtrail-sec -description: Create a DevTrail Security Assessment (SEC) document. Interactive step-by-step flow that gathers scope, threat model methodology, and OWASP ASVS level, then generates a pre-filled SEC document based on code context. Always marks as draft with review_required. +name: straymark-sec +description: Create a StrayMark Security Assessment (SEC) document. Interactive step-by-step flow that gathers scope, threat model methodology, and OWASP ASVS level, then generates a pre-filled SEC document based on code context. Always marks as draft with review_required. allowed-tools: Read, Write, Glob, Bash(git diff *, git log *, git status *, date *, wc *) --- -# DevTrail Security Assessment Skill +# StrayMark Security Assessment Skill Create a Security Assessment document with threat modeling and OWASP ASVS compliance checks. ## Instructions -When invoked via `/devtrail-sec [component-name]`, follow these steps: +When invoked via `/straymark-sec [component-name]`, follow these steps: ### 1. Gather Assessment Scope @@ -90,7 +90,7 @@ Also scan the codebase for security-relevant patterns in the component area: ``` +------------------------------------------------------------------+ -| DevTrail Security Assessment | +| StrayMark Security Assessment | +------------------------------------------------------------------+ | | | Component: [component-name] | @@ -113,15 +113,15 @@ Wait for user confirmation before proceeding. ### 6. Check Language Configuration -Read `.devtrail/config.yml` to determine language: +Read `.straymark/config.yml` to determine language: ```yaml language: en # or es ``` Use template path based on language: -- `en` (default): `.devtrail/templates/TEMPLATE-SEC.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-SEC.md` +- `en` (default): `.straymark/templates/TEMPLATE-SEC.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-SEC.md` ### 7. Generate Document ID @@ -129,7 +129,7 @@ Determine the next sequence number: ```bash # Find existing SEC documents for today -ls .devtrail/08-security/SEC-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/08-security/SEC-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ID format: `SEC-YYYY-MM-DD-NNN` @@ -154,15 +154,15 @@ ID format: `SEC-YYYY-MM-DD-NNN` - `review_required: true` - `risk_level: high` - `confidence: medium` -5. Save to: `.devtrail/08-security/SEC-YYYY-MM-DD-NNN-[description].md` +5. Save to: `.straymark/08-security/SEC-YYYY-MM-DD-NNN-[description].md` ### 9. Report Result After creation, display: ``` -DevTrail Security Assessment created: - .devtrail/08-security/SEC-YYYY-MM-DD-NNN-description.md +StrayMark Security Assessment created: + .straymark/08-security/SEC-YYYY-MM-DD-NNN-description.md Status: draft Review required: yes @@ -176,7 +176,7 @@ DevTrail Security Assessment created: ## Expected Output Example -For invocation `/devtrail-sec authentication-api`, after the interactive flow selects STRIDE and L1, the generated document would look like: +For invocation `/straymark-sec authentication-api`, after the interactive flow selects STRIDE and L1, the generated document would look like: ```markdown --- @@ -285,7 +285,7 @@ related: [] | Decision | [APPROVED / REJECTED / CONDITIONAL] | | Conditions | [If applicable] | - + ``` ## Edge Cases diff --git a/.claude/skills/straymark-status/SKILL.md b/.claude/skills/straymark-status/SKILL.md new file mode 100644 index 0000000..31c07da --- /dev/null +++ b/.claude/skills/straymark-status/SKILL.md @@ -0,0 +1,125 @@ +--- +name: straymark-status +description: Show StrayMark documentation status. Use to verify if AI agents properly documented their changes. +allowed-tools: Read, Glob, Bash(git diff *, git log *, git status *, date *, straymark analyze *) +--- + +# StrayMark Status Skill + +This skill checks the documentation status of the StrayMark in the current project. + +## Instructions + +When invoked, perform the following checks and display the results: + +### 1. Find Recent StrayMark Documents + +Search for StrayMark documents created or modified in the last hour: + +```bash +# Get documents modified in the last hour +git log --since="1 hour ago" --name-only --pretty=format: -- ".straymark/**/*.md" | sort -u | grep -v "^$" +``` + +If git is not available or the directory is not a git repo, use file modification times. +Check these directories for each document type: + +| Type | Prefix | Directory | +|------|--------|-----------| +| AILOG | `AILOG-` | `.straymark/07-ai-audit/agent-logs/` | +| AIDEC | `AIDEC-` | `.straymark/07-ai-audit/decisions/` | +| ADR | `ADR-` | `.straymark/02-design/decisions/` | +| ETH | `ETH-` | `.straymark/07-ai-audit/ethical-reviews/` | +| REQ | `REQ-` | `.straymark/01-requirements/` | +| TES | `TES-` | `.straymark/04-testing/` | +| INC | `INC-` | `.straymark/05-operations/incidents/` | +| TDE | `TDE-` | `.straymark/06-evolution/technical-debt/` | +| SEC | `SEC-` | `.straymark/08-security/` | +| MCARD | `MCARD-` | `.straymark/09-ai-models/` | +| SBOM | `SBOM-` | `.straymark/07-ai-audit/` | +| DPIA | `DPIA-` | `.straymark/07-ai-audit/ethical-reviews/` | + +Also enumerate **Charters** (bounded units of work — distinct from doc types; see STRAYMARK.md §15): + +```bash +# Charters list with status counts (declared / in-progress / closed) +straymark charter list 2>/dev/null +``` + +If the project has no Charters yet but the work clearly fits the trigger (multi-session implementation block, >5 tasks across phases, audit value), surface that as a gap in the Display Results step and recommend `/straymark-charter-new`. + +### 2. Find Modified Source Files + +Identify source files that were modified and might need documentation: + +```bash +# Get modified files (staged and unstaged) +git diff --name-only HEAD~1..HEAD 2>/dev/null || git diff --name-only +``` + +Filter to show only files that might need documentation: +- Exclude: `*.md`, `*.json`, `*.yml`, `*.yaml`, `*.lock`, `package-lock.json` +- Include: `*.ts`, `*.js`, `*.tsx`, `*.jsx`, `*.py`, `*.go`, `*.rs`, `*.java`, `*.cs`, `*.rb`, `*.php` + +Run complexity analysis on modified source files: + +```bash +# Analyze complexity of changed files (primary method for AILOG trigger) +straymark analyze --output json 2>/dev/null +# If CLI unavailable, fall back to line count heuristic in step 3 +``` + +### 3. Analyze Documentation Gaps + +For each modified source file, check if there's a corresponding StrayMark document: +- Complex code (`straymark analyze` reports `summary.above_threshold > 0`; **fallback** if CLI unavailable: >20 lines of business logic) should have an AILOG +- Security-related files (auth, crypto, secrets) should have a SEC assessment +- Architecture/structural changes should have an ADR +- AI/ML model changes should have a MCARD +- Dependency changes (`package.json`, `Cargo.toml`, `go.mod`, etc.) should have an SBOM +- Changes involving personal data processing should have a DPIA +- Test files should have a TES record +- Bug fixes or incidents should have an INC record +- Multi-session implementation blocks (>1 day, >5 tasks, multi-phase) should have an open or closed **Charter** at `.straymark/charters/` + +### 4. Display Results + +Format the output as follows: + +``` +StrayMark Status +================================================================================ + +Recent Documents (last hour): + [checkmark] AILOG-2025-01-27-001-implement-auth.md + [checkmark] AIDEC-2025-01-27-001-auth-strategy.md + +Modified Files Without Documentation: + [warning] src/auth/login.ts (cognitive: 12, threshold: 8) + [warning] src/api/users.ts (cognitive: 9, threshold: 8) + +Summary: + Documents created: 2 + Files needing review: 2 + +Use /straymark-status after making changes to verify documentation compliance. +``` + +### Symbol Legend + +- `[checkmark]` = Documentation exists (use checkmark symbol) +- `[warning]` = May need documentation (use warning symbol) +- `[info]` = Informational (use info symbol) + +### Edge Cases + +1. **No git repository**: Show message explaining git is required for full functionality +2. **No recent documents**: Show "No StrayMark documents created in the last hour" +3. **No modified files**: Show "No source files modified recently" +4. **Empty .straymark directory**: Show warning that StrayMark may not be properly set up + +### Additional Notes + +- This skill is read-only and does not create or modify files +- Run this after completing development tasks to verify documentation compliance +- If files need documentation, remind the user of the StrayMark rules diff --git a/.cursor/rules/devtrail.md b/.cursor/rules/devtrail.md deleted file mode 100644 index ee1f927..0000000 --- a/.cursor/rules/devtrail.md +++ /dev/null @@ -1,375 +0,0 @@ -# DevTrail - Cursor Rules - - -# DevTrail - Documentation Governance Rules - -> **This file is automatically managed by DevTrail CLI.** -> Read and follow these rules when working on this project. -> For complete rules: `.devtrail/00-governance/AGENT-RULES.md` - ---- - -## Governance Context - -These rules operationalize **ISO/IEC 42001:2023** (AI Management System) — DevTrail's vertebral standard. Following them produces documented evidence compatible with: - -- **EU AI Act** (Regulation 2024/1689) — risk classification, transparency, incident reporting -- **NIST AI RMF 1.0 + 600-1** — risk management functions and generative AI risk profiles -- **GDPR** — data protection impact assessments and privacy safeguards - -> See `AI-GOVERNANCE-POLICY.md` for the full ISO 42001 Annex A control mapping. - ---- - -## 1. Fundamental Principle - -> **"No significant change without a documented trace."** - ---- - -## 2. Language Configuration - -Check `.devtrail/config.yml` for the project's language setting: - -```yaml -language: en # Options: en, es (default: en) -``` - -**Template paths based on language:** - -| Language | Template Path | -|----------|---------------| -| `en` (default) | `.devtrail/templates/TEMPLATE-*.md` | -| `es` | `.devtrail/templates/i18n/es/TEMPLATE-*.md` | - -If the config file doesn't exist or `language` is not set, use English (`en`) as default. - ---- - -## 3. Documentation Reporting - -At the end of each task, you MUST report your DevTrail documentation status: - -**If you created documentation:** -``` -DevTrail: Created AILOG-2025-01-27-001-implement-auth.md -``` - -**If documentation was not needed:** -``` -DevTrail: No documentation required (minor change / below complexity threshold) -``` - -**If you should have documented but didn't:** -``` -DevTrail: Documentation pending - review required -``` - -This transparency helps users verify compliance with DevTrail rules. - ---- - -## 4. Agent Identity - -When working on this project: - -- **Identify yourself** with your platform and version (e.g., `claude-code-v1.0`, `gemini-cli-v1.0`, `copilot-cli-v1.0`) -- **Declare** your confidence level in decisions: `high | medium | low` -- **Record** your identification in the `agent:` field of the metadata - ---- - -## 5. Git Operations - -> **CRITICAL: Never commit directly to `main` branch.** - -All changes must go through feature/fix branches and Pull Requests. - -### Branch Prefixes - -| Prefix | Purpose | -|--------|---------| -| `feature/` or `feat/` | New features | -| `fix/` | Bug fixes | -| `hotfix/` | Urgent production fixes | -| `docs/` | Documentation only | -| `refactor/` | Code refactoring | -| `test/` | Test changes | - -### Conventional Commits - -| Prefix | Use Case | -|--------|----------| -| `feat:` | New feature | -| `fix:` | Bug fix | -| `docs:` | Documentation only | -| `refactor:` | No behavior change | -| `chore:` | Maintenance | - -### Quick Workflow - -```bash -git checkout main && git pull origin main -git checkout -b fix/descriptive-name -# ... make changes and commits ... -git push -u origin fix/descriptive-name -gh pr create --title "fix: description" --body "..." -``` - -> **Full details:** `.devtrail/00-governance/GIT-BRANCHING-STRATEGY.md` - ---- - -## 6. When to Document - -### MANDATORY (create document) - -| Situation | Action | -|-----------|--------| -| Code complexity above threshold | Create AILOG — run `devtrail analyze --output json`; fallback: >20 lines | -| Decision between technical alternatives | Create AIDEC | -| Changes in auth/authorization/PII | Create AILOG (`risk_level: high`) + ETH draft | -| Changes in public API or DB schema | Create AILOG + consider ADR | -| Changes in ML models or AI prompts | Create AILOG + human review | -| Security-critical dependency changes | Create AILOG + human review | -| OTel instrumentation changes | Create AILOG + tag `observabilidad` | - -### DO NOT DOCUMENT - -- Trivial changes (whitespace, typos, formatting) -- Sensitive information (credentials, tokens, API keys) - ---- - -## 7. File Naming Convention - -``` -[TYPE]-[YYYY-MM-DD]-[NNN]-[description].md -``` - -**Example**: `AILOG-2025-01-27-001-implement-oauth.md` - ---- - -## 8. Minimum Metadata - -```yaml ---- -id: AILOG-2026-03-25-001 -title: Brief description -status: accepted -created: 2026-03-25 -agent: your-agent-id-v1.0 -confidence: high | medium | low -review_required: true | false -risk_level: low | medium | high | critical -tags: [oauth, authentication, api] -related: - - ADR-2026-01-20-001-use-jwt-tokens.md -# Optional regulatory fields (activate by context): -# eu_ai_act_risk: not_applicable -# nist_genai_risks: [] -# iso_42001_clause: [] -# observability_scope: none ---- -``` - -### Tags - -- Use **kebab-case** keywords: `sqlite`, `api-design`, `gnome-integration` -- 3 to 8 tags per document — describe topic, technology, or component -- Tags enable search and categorization in `devtrail explore` - -### Related - -- Reference other **DevTrail documents** by filename (with `.md`): `AILOG-2025-01-27-001-implement-oauth.md` -- For documents in subdirectories, include path from `.devtrail/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-file.md` -- For documents in the same directory, filename alone is sufficient -- **Do not** use task IDs, issue numbers, or URLs — those go in the document body - ---- - -## 9. Autonomy Limits - -| Type | Agent can do | Requires human | -|------|----------|----------------| -| **AILOG** | Create freely | — | -| **AIDEC** | Create freely | — | -| **SBOM** | Create freely | — | -| **ETH** | Create draft | Approval | -| **ADR** | Create draft | Review | -| **SEC** | Create draft | Approval (always) | -| **MCARD** | Create draft | Approval (always) | -| **DPIA** | Create draft | Approval (always) | -| **REQ** | Propose | Validation | -| **TES** | Propose | Validation | -| **INC** | Contribute analysis | Conclusions | -| **TDE** | Identify | Prioritize | - ---- - -## 10. Documentation Map - -> **IMPORTANT**: This is the complete project structure. -> Not everything is loaded in this session, but any document can be accessed when needed. - -``` -.devtrail/ -├── 00-governance/ ← POLICIES AND RULES -│ ├── PRINCIPLES.md # Project guiding principles -│ ├── DOCUMENTATION-POLICY.md # Complete documentation policy -│ ├── AGENT-RULES.md # Detailed rules for AI agents -│ └── exceptions/ # Documented exceptions -│ -├── 01-requirements/ ← REQUIREMENTS (REQ) -│ └── [REQ-*.md] # System requirements -│ -├── 02-design/ ← DESIGN -│ └── decisions/ # ADRs (Architecture Decision Records) -│ └── [ADR-*.md] -│ -├── 03-implementation/ ← IMPLEMENTATION GUIDES -│ └── [technical guides] -│ -├── 04-testing/ ← TESTING (TES) -│ └── [TES-*.md] # Test strategies and plans -│ -├── 05-operations/ ← OPERATIONS -│ ├── [runbooks] -│ └── incidents/ # Post-mortems (INC) -│ └── [INC-*.md] -│ -├── 06-evolution/ ← EVOLUTION -│ └── technical-debt/ # Technical debt (TDE) -│ └── [TDE-*.md] -│ -├── 07-ai-audit/ ← AI AGENT AUDIT -│ ├── agent-logs/ # Action logs (AILOG) -│ │ └── [AILOG-*.md] -│ ├── decisions/ # Agent decisions (AIDEC) -│ │ └── [AIDEC-*.md] -│ └── ethical-reviews/ # Ethical reviews (ETH, DPIA) -│ └── [ETH-*.md] -│ -├── 08-security/ ← SECURITY ASSESSMENTS (SEC) -│ └── [SEC-*.md] -│ -├── 09-ai-models/ ← AI MODEL CARDS (MCARD) -│ └── [MCARD-*.md] -│ -├── templates/ ← TEMPLATES (12 types) -│ -└── QUICK-REFERENCE.md ← 1-page quick reference -``` - ---- - -## 11. When to Load Additional Documents - -| Situation | Document to load | -|-----------|------------------| -| Going to create an AILOG | `.devtrail/templates/TEMPLATE-AILOG.md` | -| Going to create an AIDEC | `.devtrail/templates/TEMPLATE-AIDEC.md` | -| Going to create an ADR | `.devtrail/templates/TEMPLATE-ADR.md` | -| Going to create a REQ | `.devtrail/templates/TEMPLATE-REQ.md` | -| Questions about naming or metadata | `.devtrail/00-governance/DOCUMENTATION-POLICY.md` | -| Questions about autonomy limits | `.devtrail/00-governance/AGENT-RULES.md` | -| Need to see existing requirements | List `.devtrail/01-requirements/` | -| Need to see existing ADRs | List `.devtrail/02-design/decisions/` | -| Need to see technical debt | List `.devtrail/06-evolution/technical-debt/` | - ---- - -## 12. Workflow - -``` -1. EVALUATE if the change requires documentation (see section 6) - | - v -2. LOAD the corresponding template (see section 11) - | - v -3. CREATE the document with correct naming - [TYPE]-[YYYY-MM-DD]-[NNN]-[description].md - | - v -4. If risk_level: high/critical or confidence: low - -> Mark review_required: true -``` - ---- - -## 13. Quick Type Reference - -| Prefix | Name | Location | -|--------|------|----------| -| `AILOG` | AI Action Log | `.devtrail/07-ai-audit/agent-logs/` | -| `AIDEC` | AI Decision | `.devtrail/07-ai-audit/decisions/` | -| `ETH` | Ethical Review | `.devtrail/07-ai-audit/ethical-reviews/` | -| `ADR` | Architecture Decision Record | `.devtrail/02-design/decisions/` | -| `REQ` | Requirement | `.devtrail/01-requirements/` | -| `TES` | Test Plan | `.devtrail/04-testing/` | -| `INC` | Incident Post-mortem | `.devtrail/05-operations/incidents/` | -| `TDE` | Technical Debt | `.devtrail/06-evolution/technical-debt/` | -| `SEC` | Security Assessment | `.devtrail/08-security/` | -| `MCARD` | Model/System Card | `.devtrail/09-ai-models/` | -| `SBOM` | Software Bill of Materials | `.devtrail/07-ai-audit/` | -| `DPIA` | Data Protection Impact Assessment | `.devtrail/07-ai-audit/ethical-reviews/` | - ---- - -## 14. Regulatory Alignment - -DevTrail is aligned with the following standards and regulations: - -| Standard | Role in DevTrail | Key Documents | -|----------|-----------------|---------------| -| **ISO/IEC 42001:2023** | Vertebral standard — AI Management System | AI-GOVERNANCE-POLICY.md | -| **EU AI Act** | Risk classification, incident reporting, transparency | ETH, INC, AILOG regulatory fields | -| **NIST AI RMF / 600-1** | Risk management, 12 GenAI risk categories | ETH, AILOG | -| **ISO/IEC 25010:2023** | Software quality model (9 characteristics) | REQ, ADR | -| **ISO/IEC/IEEE 29148:2018** | Requirements engineering | REQ | -| **ISO/IEC/IEEE 29119-3:2021** | Software testing documentation | TES | -| **GDPR** | Data protection and privacy | ETH (Data Privacy) | -| **OpenTelemetry** | Observability (optional, complementary) | Tag `observabilidad` | -| **C4 Model** | Architecture visualization in ADR documents | ADR (Mermaid diagrams) | - -> **Reference**: See `AI-GOVERNANCE-POLICY.md` for the full ISO 42001 Annex A mapping to DevTrail documents. - ---- - -## Directive Injection Markers - -DevTrail uses HTML comment markers to manage injected content in agent configuration files (CLAUDE.md, GEMINI.md, .cursorrules, etc.): - -```html - -... managed content ... - -``` - -- Content between these markers is managed by `devtrail init`, `update`, and `repair` -- Do not remove or modify these markers manually — they are required for safe updates -- If markers are missing from a target file, DevTrail appends the content block at the end - ---- - -*DevTrail | [GitHub](https://github.com/StrangeDaysTech/devtrail)* -*[Strange Days Tech](https://strangedays.tech) — Because every change tells a story.* - - -## DevTrail Documentation Rules - -Identity: Use `cursor-v{version}` in the `agent:` field. - -Document when: complex code — run `devtrail analyze --output json`, AILOG if `above_threshold > 0` (fallback: >20 lines), alternatives (AIDEC), auth/PII (AILOG+ETH), API/DB changes (AILOG+ADR), ML/prompts (AILOG+review). - -Review required: ETH, ADR, SEC, MCARD, DPIA → always. risk_level high/critical → always. - -Never document: credentials, tokens, API keys, PII. - -Regulatory fields (when relevant): eu_ai_act_risk, nist_genai_risks, iso_42001_clause. - -Observability: No PII in OTel attributes. Tag instrumentation changes with `observabilidad`. - -Naming: [TYPE]-[YYYY-MM-DD]-[NNN]-[description].md diff --git a/.cursor/rules/straymark.md b/.cursor/rules/straymark.md new file mode 100644 index 0000000..df02b21 --- /dev/null +++ b/.cursor/rules/straymark.md @@ -0,0 +1,495 @@ +# StrayMark - Cursor Rules + + +# StrayMark - Documentation Governance Rules + +> **This file is automatically managed by StrayMark CLI.** +> Read and follow these rules when working on this project. +> For complete rules: `.straymark/00-governance/AGENT-RULES.md` + +--- + +## Why these rules exist + +StrayMark externalizes the cognitive discipline of senior software engineering — explicit scope, declared decisions, named risks, recorded alternatives, audited trails — into versioned files that live alongside the code. The intent is to constrain the agent's decision space so AI-assisted work stays coherent across many turns instead of drifting into hidden technical debt. + +As a side effect of doing the engineering work this way, the artifacts produced map cleanly onto the major AI governance frameworks. The rules are written for the engineering work first; the compliance evidence is what falls out when the work is done with discipline. + +**Frameworks the resulting evidence aligns with:** + +- **ISO/IEC 42001:2023** (AI Management System) — vertebral standard for governance structure +- **EU AI Act** (Regulation 2024/1689) — risk classification, transparency, incident reporting +- **NIST AI RMF 1.0 + 600-1** — risk management functions and generative AI risk profiles +- **GDPR** — data protection impact assessments and privacy safeguards + +**Optional regional scope** — when `.straymark/config.yml` declares `regional_scope: china`, the framework additionally produces evidence for: + +- **TC260 AI Safety Governance Framework v2.0** — risk grading (TC260RA) +- **PIPL** (Personal Information Protection Law) — PIPIA, retention ≥ 3 years +- **GB 45438-2025** *(mandatory)* — AI-generated content labeling (AILABEL) +- **CAC Algorithm Filing** — algorithm registration (CACFILE) +- **GB/T 45652-2025** — pre-training & fine-tuning data security +- **CSL 2026** — cybersecurity incident reporting (1h / 4h+72h+30d windows) + +> See `AI-GOVERNANCE-POLICY.md` for the ISO 42001 Annex A control mapping and `CHINA-REGULATORY-FRAMEWORK.md` for the China coverage matrix. The product-level rationale lives in [`Propuesta/straymark-design-principles.md`](https://github.com/StrangeDaysTech/straymark/blob/main/Propuesta/straymark-design-principles.md). + +--- + +## 1. Fundamental Principle + +> **"No significant change without a documented trace — and a constrained decision space for the agent."** + +--- + +## 2. Language Configuration + +Check `.straymark/config.yml` for the project's language setting: + +```yaml +language: en # Options: en, es, zh-CN (default: en) +``` + +**Template paths based on language:** + +| Language | Template Path | +|----------|---------------| +| `en` (default) | `.straymark/templates/TEMPLATE-*.md` | +| `es` | `.straymark/templates/i18n/es/TEMPLATE-*.md` | +| `zh-CN` | `.straymark/templates/i18n/zh-CN/TEMPLATE-*.md` | + +If the config file doesn't exist or `language` is not set, use English (`en`) as default. + +--- + +## 3. Documentation Reporting + +At the end of each task, you MUST report your StrayMark documentation status: + +**If you created documentation:** +``` +StrayMark: Created AILOG-2025-01-27-001-implement-auth.md +``` + +**If documentation was not needed:** +``` +StrayMark: No documentation required (minor change / below complexity threshold) +``` + +**If you should have documented but didn't:** +``` +StrayMark: Documentation pending - review required +``` + +This transparency helps users verify compliance with StrayMark rules. + +--- + +## 4. Agent Identity + +When working on this project: + +- **Identify yourself** with your platform and version (e.g., `claude-code-v1.0`, `gemini-cli-v1.0`, `copilot-cli-v1.0`) +- **Declare** your confidence level in decisions: `high | medium | low` +- **Record** your identification in the `agent:` field of the metadata + +--- + +## 5. Git Operations + +> **CRITICAL: Never commit directly to `main` branch.** + +All changes must go through feature/fix branches and Pull Requests. + +### Branch Prefixes + +| Prefix | Purpose | +|--------|---------| +| `feature/` or `feat/` | New features | +| `fix/` | Bug fixes | +| `hotfix/` | Urgent production fixes | +| `docs/` | Documentation only | +| `refactor/` | Code refactoring | +| `test/` | Test changes | + +### Conventional Commits + +| Prefix | Use Case | +|--------|----------| +| `feat:` | New feature | +| `fix:` | Bug fix | +| `docs:` | Documentation only | +| `refactor:` | No behavior change | +| `chore:` | Maintenance | + +### Quick Workflow + +```bash +git checkout main && git pull origin main +git checkout -b fix/descriptive-name +# ... make changes and commits ... +git push -u origin fix/descriptive-name +gh pr create --title "fix: description" --body "..." +``` + +> **Full details:** `.straymark/00-governance/GIT-BRANCHING-STRATEGY.md` + +--- + +## 6. When to Document + +### MANDATORY (create document) + +| Situation | Action | +|-----------|--------| +| Code complexity above threshold | Create AILOG — run `straymark analyze --output json`; fallback: >20 lines | +| Decision between technical alternatives | Create AIDEC | +| Changes in auth/authorization/PII | Create AILOG (`risk_level: high`) + ETH draft | +| Changes in public API or DB schema | Create AILOG + consider ADR | +| Changes in ML models or AI prompts | Create AILOG + human review | +| Security-critical dependency changes | Create AILOG + human review | +| OTel instrumentation changes | Create AILOG + tag `observabilidad` | +| Multi-session implementation block (>1 day, >5 tasks across phases) | Declare a **Charter** — `straymark charter new`. See section 15. | +| Transversal technical debt — heritage from prior Charter, applies to multiple modules, or requires dedicated Charter to remediate | Create **TDE** — distinct from per-Charter `R`. See `.straymark/00-governance/AGENT-RULES.md` §3 for TDE vs `R` disambiguation. | + +### DO NOT DOCUMENT + +- Trivial changes (whitespace, typos, formatting) +- Sensitive information (credentials, tokens, API keys) + +--- + +## 7. File Naming Convention + +``` +[TYPE]-[YYYY-MM-DD]-[NNN]-[description].md +``` + +**Example**: `AILOG-2025-01-27-001-implement-oauth.md` + +--- + +## 8. Minimum Metadata + +```yaml +--- +id: AILOG-2026-03-25-001 +title: Brief description +status: accepted +created: 2026-03-25 +agent: your-agent-id-v1.0 +confidence: high | medium | low +review_required: true | false +risk_level: low | medium | high | critical +tags: [oauth, authentication, api] +related: + - ADR-2026-01-20-001-use-jwt-tokens.md +# Optional regulatory fields (activate by context): +# eu_ai_act_risk: not_applicable +# nist_genai_risks: [] +# iso_42001_clause: [] +# observability_scope: none +--- +``` + +### Tags + +- Use **kebab-case** keywords: `sqlite`, `api-design`, `gnome-integration` +- 3 to 8 tags per document — describe topic, technology, or component +- Tags enable search and categorization in `straymark explore` + +### Related + +- Reference other **StrayMark documents** by filename (with `.md`): `AILOG-2025-01-27-001-implement-oauth.md` +- For documents in subdirectories, include path from `.straymark/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-file.md` +- For documents in the same directory, filename alone is sufficient +- **Do not** use task IDs, issue numbers, or URLs — those go in the document body + +--- + +## 9. Autonomy Limits + +| Type | Agent can do | Requires human | +|------|----------|----------------| +| **AILOG** | Create freely | — | +| **AIDEC** | Create freely | — | +| **SBOM** | Create freely | — | +| **ETH** | Create draft | Approval | +| **ADR** | Create draft | Review | +| **SEC** | Create draft | Approval (always) | +| **MCARD** | Create draft | Approval (always) | +| **DPIA** | Create draft | Approval (always) | +| **REQ** | Propose | Validation | +| **TES** | Propose | Validation | +| **INC** | Contribute analysis | Conclusions | +| **TDE** | Identify | Prioritize | +| **PIPIA** *(china)* | Create draft | Approval (always) | +| **CACFILE** *(china)* | Create draft | Approval (always — counsel + compliance officer before submission) | +| **TC260RA** *(china)* | Create draft | Approval (always) | +| **AILABEL** *(china)* | Create draft | Approval (always — before deployment) | +| **Charter** | Scaffold via `charter new`; fill scope, files, risks, tasks | Operator owns the *trigger* and lifecycle transitions (`declared` → `in-progress` → `closed`). See section 15. | + +--- + +## 10. Documentation Map + +> **IMPORTANT**: This is the complete project structure. +> Not everything is loaded in this session, but any document can be accessed when needed. + +``` +.straymark/ +├── 00-governance/ ← POLICIES AND RULES +│ ├── PRINCIPLES.md # Project guiding principles +│ ├── DOCUMENTATION-POLICY.md # Complete documentation policy +│ ├── AGENT-RULES.md # Detailed rules for AI agents +│ └── exceptions/ # Documented exceptions +│ +├── 01-requirements/ ← REQUIREMENTS (REQ) +│ └── [REQ-*.md] # System requirements +│ +├── 02-design/ ← DESIGN +│ └── decisions/ # ADRs (Architecture Decision Records) +│ └── [ADR-*.md] +│ +├── 03-implementation/ ← IMPLEMENTATION GUIDES +│ └── [technical guides] +│ +├── 04-testing/ ← TESTING (TES) +│ └── [TES-*.md] # Test strategies and plans +│ +├── 05-operations/ ← OPERATIONS +│ ├── [runbooks] +│ └── incidents/ # Post-mortems (INC) +│ └── [INC-*.md] +│ +├── 06-evolution/ ← EVOLUTION +│ └── technical-debt/ # Technical debt (TDE) +│ └── [TDE-*.md] +│ +├── 07-ai-audit/ ← AI AGENT AUDIT +│ ├── agent-logs/ # Action logs (AILOG) +│ │ └── [AILOG-*.md] +│ ├── decisions/ # Agent decisions (AIDEC) +│ │ └── [AIDEC-*.md] +│ ├── ethical-reviews/ # Ethical reviews (ETH, DPIA, PIPIA*) +│ │ └── [ETH-*.md] +│ ├── regulatory-filings/ # CAC algorithm filings (CACFILE*) +│ │ └── [CACFILE-*.md] +│ └── risk-assessments/ # TC260 risk assessments (TC260RA*) +│ └── [TC260RA-*.md] +│ +├── 08-security/ ← SECURITY ASSESSMENTS (SEC) +│ └── [SEC-*.md] +│ +├── 09-ai-models/ ← AI MODEL CARDS (MCARD) +│ ├── [MCARD-*.md] +│ └── labeling/ # GB 45438 content labeling plans (AILABEL*) +│ └── [AILABEL-*.md] +│ +├── charters/ ← CHARTERS — BOUNDED UNITS OF WORK +│ ├── [NN-slug.md] # Declarative ex-ante scope (filename: NN-slug.md, NOT TYPE-YYYY-...) +│ └── [NN-slug.telemetry.yaml] # Post-close telemetry (created by `straymark charter close`) +│ +├── templates/ ← TEMPLATES (12 base + 4 China* + Charter) + +* Only created when regional_scope: china is enabled in .straymark/config.yml. +│ +└── QUICK-REFERENCE.md ← 1-page quick reference +``` + +--- + +## 11. When to Load Additional Documents + +| Situation | Document to load | +|-----------|------------------| +| Going to create an AILOG | `.straymark/templates/TEMPLATE-AILOG.md` | +| Going to create an AIDEC | `.straymark/templates/TEMPLATE-AIDEC.md` | +| Going to create an ADR | `.straymark/templates/TEMPLATE-ADR.md` | +| Going to create a REQ | `.straymark/templates/TEMPLATE-REQ.md` | +| Questions about naming or metadata | `.straymark/00-governance/DOCUMENTATION-POLICY.md` | +| Questions about autonomy limits | `.straymark/00-governance/AGENT-RULES.md` | +| Need to see existing requirements | List `.straymark/01-requirements/` | +| Need to see existing ADRs | List `.straymark/02-design/decisions/` | +| Need to see technical debt | List `.straymark/06-evolution/technical-debt/` | +| Going to declare a Charter | `.straymark/templates/charter/charter-template.md` (or `straymark charter new`) | +| Need to see existing Charters | `straymark charter list` (or list `.straymark/charters/`) | +| SpecKit user — when does a feature yield a Charter? | `.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md` | +| Wondering why agents surface things you didn't ask | `.straymark/00-governance/EMERGENT-OBSERVATION-DESIGN.md` | + +--- + +## 12. Workflow + +``` +1. EVALUATE if the change requires documentation (see section 6) + | + v +2. LOAD the corresponding template (see section 11) + | + v +3. CREATE the document with correct naming + [TYPE]-[YYYY-MM-DD]-[NNN]-[description].md + | + v +4. If risk_level: high/critical or confidence: low + -> Mark review_required: true +``` + +--- + +## 13. Quick Type Reference + +| Prefix | Name | Location | +|--------|------|----------| +| `AILOG` | AI Action Log | `.straymark/07-ai-audit/agent-logs/` | +| `AIDEC` | AI Decision | `.straymark/07-ai-audit/decisions/` | +| `ETH` | Ethical Review | `.straymark/07-ai-audit/ethical-reviews/` | +| `ADR` | Architecture Decision Record | `.straymark/02-design/decisions/` | +| `REQ` | Requirement | `.straymark/01-requirements/` | +| `TES` | Test Plan | `.straymark/04-testing/` | +| `INC` | Incident Post-mortem | `.straymark/05-operations/incidents/` | +| `TDE` | Technical Debt | `.straymark/06-evolution/technical-debt/` | +| `SEC` | Security Assessment | `.straymark/08-security/` | +| `MCARD` | Model/System Card | `.straymark/09-ai-models/` | +| `SBOM` | Software Bill of Materials | `.straymark/07-ai-audit/` | +| `DPIA` | Data Protection Impact Assessment | `.straymark/07-ai-audit/ethical-reviews/` | +| `Charter` | Bounded unit of work (filename `NN-slug.md`, not `TYPE-YYYY-…`) | `.straymark/charters/` | + +--- + +## 14. Regulatory Alignment + +StrayMark is aligned with the following standards and regulations: + +| Standard | Role in StrayMark | Key Documents | +|----------|-----------------|---------------| +| **ISO/IEC 42001:2023** | Vertebral standard — AI Management System | AI-GOVERNANCE-POLICY.md | +| **EU AI Act** | Risk classification, incident reporting, transparency | ETH, INC, AILOG regulatory fields | +| **NIST AI RMF / 600-1** | Risk management, 12 GenAI risk categories | ETH, AILOG | +| **ISO/IEC 25010:2023** | Software quality model (9 characteristics) | REQ, ADR | +| **ISO/IEC/IEEE 29148:2018** | Requirements engineering | REQ | +| **ISO/IEC/IEEE 29119-3:2021** | Software testing documentation | TES | +| **GDPR** | Data protection and privacy | ETH (Data Privacy) | +| **OpenTelemetry** | Observability (optional, complementary) | Tag `observabilidad` | +| **C4 Model** | Architecture visualization in ADR documents | ADR (Mermaid diagrams) | + +> **Reference**: See `AI-GOVERNANCE-POLICY.md` for the full ISO 42001 Annex A mapping to StrayMark documents. + +--- + +## 15. Charters — bounded units of work + +A **Charter** is StrayMark's artifact for an *implementation block that is too big to track as a single AILOG and too small to deserve its own product spec*. It pairs **declarative ex-ante scope** (files to modify, risks, tasks, effort estimate) with **ex-post telemetry** (drift detection, external audit, lessons learned). Concretely: the kind of work that takes >1 day, spans >5 tasks, or crosses multiple sessions where an agent might lose the thread. + +Charters are **conceptually distinct** from the 12+4 document types listed in section 13: + +- They live at `.straymark/charters/NN-slug.md` (sequential prefix, not date-prefix). +- Their lifecycle is `declared` → `in-progress` → `closed`, persisted in frontmatter as the source of truth. +- Telemetry sits beside them as `NN-slug.telemetry.yaml`, written by `straymark charter close`. +- External audits resolve to `.straymark/audits/CHARTER-NN/` and merge back into telemetry. + +### When to declare a Charter + +Trigger row in section 6 names the heuristic; expanded: + +- The work spans **more than one working session** and you need a stable scope contract you can drift-check at close. +- The work has **5+ named tasks** with a topological order (e.g., a SpecKit `tasks.md`). +- The work warrants **external audit** at completion (cross-model review, cross-team review). +- You want **measurable telemetry**: time-to-close, drift count, lessons that feed forward. + +### Charter lifecycle + +| Stage | What happens | CLI | +|-------|--------------|-----| +| **Declared** | Operator scaffolds Charter, fills scope/files/risks/tasks. Status `declared`. | `straymark charter new` | +| **In progress** | Operator flips status to `in-progress` when execution starts. Day-to-day work continues to produce AILOGs. | (manual frontmatter edit) | +| **Batch update** *(multi-batch only, fw-4.14.0+)* | For Charters spanning 3+ batches or >1 day, the AILOG carries a `## Batch Ledger` with one `### Batch N` entry per batch starting as `(pending)`. After each batch commit lands, fill the entry **before pushing** so the AILOG update and the work ride the same push. Single-batch Charters skip this step entirely. | `straymark charter batch-complete CHARTER-NN ` | +| **Drift check** | Before closing, verify declared files vs. actual git diff. AILOG-suppressed paths are noise-filtered; pending `### Batch N` entries cause a hard fail (`--no-batch-ledger-check` bypasses). | `straymark charter drift` | +| **External audit** *(optional)* | Generate prompt → run N auditor CLIs → consolidate → merge into telemetry. | `straymark charter audit` + `/straymark-audit-prompt` + `/straymark-audit-execute` + `/straymark-audit-review` | +| **Closed** | Telemetry yaml emitted; status flips to `closed`; charter is now an audit artifact. | `straymark charter close` | + +### How Charters relate to existing artifacts + +- A Charter **does not replace** AILOGs. AILOGs document individual blocks of code work; the Charter wraps them as a unit. `originating_ailogs:` in the Charter frontmatter declares which AILOGs the Charter contains. +- A Charter **does not replace** ADRs. ADRs document architectural decisions; a Charter may reference them in `originating_spec` or in body sections. +- A Charter **bridges SpecKit features** (`specs/NNN-feature/spec.md`) and execution. See `.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md` for granularity heuristics and creation timing. + +### Quick CLI surface + +```bash +straymark charter new # scaffold a Charter (interactive) +straymark charter list # enumerate Charters with status/effort/origin +straymark charter status CHARTER-NN # detailed view of one Charter +straymark charter drift CHARTER-NN # file-vs-commit drift, AILOG-aware + Batch Ledger gate +straymark charter batch-complete CHARTER-NN # fill AILOG `## Batch Ledger` Batch (multi-batch only) +straymark charter audit CHARTER-NN # multi-model external audit (orchestration only) +straymark charter close CHARTER-NN # record telemetry; flip status to `closed` +straymark charter refresh-suggest # SpecKit refresh recommendation (chain-level, fw-4.16.0+) — see §15.A +straymark charter amend CHARTER-NN # scaffold post-close Batch N.4 amendment (fw-4.16.0+) — see §15.B +``` + +> **Schema**: `.straymark/schemas/charter.schema.v0.json` (declarative) and `.straymark/schemas/charter-telemetry.schema.v0.json` (telemetry). Both are experimental v0 — patterns crystallize after validation against a second domain (Principle #12). + +### §15.A — Pre-declare SpecKit refresh *(fw-4.16.0+)* + +Multi-Charter modules accumulate spec drift over time. After 3+ Charters in a chain, SpecKit artifacts (`plan.md`, `data-model.md`, `contracts/*`, `quickstart.md`, `research.md`) authored at chain start tend to lag behind the implementation. The fix is a dedicated **refresh PR** between Charter-N close and Charter-(N+1) declare that integrates accumulated learnings into `research.md` (categorized buckets: reusable patterns, code gaps, discipline patterns, empirical corrections) and ratifies operator decisions. The next Charter's `## Context` cites each learning by id. + +**Trigger heuristic** — adopt when (a) chain length ≥ 3 closed Charters in the module AND (b) rolling mean of `agent_quality.r_n_plus_one_emergent_count` across last 3 > 6 AND (c) no refresh PR landed since the chain's branch point. Run: + +```bash +straymark charter refresh-suggest # read-only — prints recommendation +``` + +**Telemetry** — `charter_telemetry.pre_declare_refresh:` (optional, opt-in). See `.straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md` Pattern 1 for full mechanics. + +### §15.B — Post-close audit-driven amendment (Batch N.4) *(fw-4.16.0+)* + +External audit cycles run post-close. When Critical or High findings arrive after a Charter has been marked `status: closed`, the bounded remediation pattern is a **Batch N.4 amendment** that rides on the same execute branch: a new AILOG documents the amendment, the original AILOG receives a `## Historical correction` subsection pointing forward, and the telemetry gains a `post_close_amendment:` block. Apply only when (a) findings are Critical/High, (b) the Charter's closure criterion is materially unmet, AND (c) the fix surface fits in one cohesive PR (~< 25 files, no architectural reopen). Larger or architectural fixes warrant a new Charter. + +```bash +straymark charter amend CHARTER-NN \ # scaffolds the new AILOG, edits the original, prints YAML + --trigger external_audit \ + --findings-closed 5 \ + --ailog-title "post-close remediation — DI wiring + retry" +``` + +The command does not touch git — the operator decides when to commit. The `straymark charter audit --merge-reports --merge-into ` path tolerates `external_audit: []` placeholders in v0.2+ schema so the round-trip with `post_close_amendment` is smooth. See `.straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md` Pattern 2 for full mechanics. + +--- + +## Directive Injection Markers + +StrayMark uses HTML comment markers to manage injected content in agent configuration files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.cursorrules`, `.cursor/rules/straymark.md`): + +```html + +... managed content ... + +``` + +- Content between these markers is managed by `straymark init`, `update`, and `repair` +- Do not remove or modify these markers manually — they are required for safe updates +- If markers are missing from a target file, StrayMark appends the content block at the end +- **Missing-target behavior** *(refined in fw-4.16.2 / cli-3.14.1)*: `straymark init`, `straymark update-framework`, and `straymark repair` all walk `dist-manifest.yml::injections:` and **create any missing target file** (with the marker block) per individual target — a single deleted directive file like `AGENTS.md` is restored without needing to re-run init or remove anything else. There is no opt-out per target short of editing the manifest. *(Historical note: through `cli-3.14.0` / `fw-4.16.1`, `straymark repair` was gated on `STRAYMARK.md` being absent and would silently skip a per-target restore; that gate was removed in `cli-3.14.1`.)* +- `AGENTS.md` is the open standard donated to the Agentic AI Foundation (Linux Foundation, 2025) and is read by Claude Code, OpenAI Codex CLI, Cursor, Aider, Devin, Sourcegraph Amp, Google Jules, Zed AI, Continue, Roo Code, Factory Droids, GitHub Copilot, Gemini CLI, Windsurf, Amazon Q and others. CLI-specific files (`CLAUDE.md`, `GEMINI.md`, etc.) coexist with `AGENTS.md` and provide platform-specific identity strings. + +--- + +*StrayMark | [GitHub](https://github.com/StrangeDaysTech/straymark)* +*[Strange Days Tech](https://strangedays.tech) — Because every change tells a story.* + +## StrayMark Documentation Rules + +Identity: Use `cursor-v{version}` in the `agent:` field. + +Document when: complex code — run `straymark analyze --output json`, AILOG if `above_threshold > 0` (fallback: >20 lines), alternatives (AIDEC), auth/PII (AILOG+ETH), API/DB changes (AILOG+ADR), ML/prompts (AILOG+review). + +Review required: ETH, ADR, SEC, MCARD, DPIA → always. risk_level high/critical → always. + +Never document: credentials, tokens, API keys, PII. + +Regulatory fields (when relevant): eu_ai_act_risk, nist_genai_risks, iso_42001_clause. + +Observability: No PII in OTel attributes. Tag instrumentation changes with `observabilidad`. + +Naming: [TYPE]-[YYYY-MM-DD]-[NNN]-[description].md diff --git a/.cursorrules b/.cursorrules index ee92cdf..3d1692d 100644 --- a/.cursorrules +++ b/.cursorrules @@ -1,46 +1,61 @@ -# DevTrail - Cursor Configuration +# StrayMark - Cursor Configuration - -# DevTrail - Documentation Governance Rules + +# StrayMark - Documentation Governance Rules -> **This file is automatically managed by DevTrail CLI.** +> **This file is automatically managed by StrayMark CLI.** > Read and follow these rules when working on this project. -> For complete rules: `.devtrail/00-governance/AGENT-RULES.md` +> For complete rules: `.straymark/00-governance/AGENT-RULES.md` --- -## Governance Context +## Why these rules exist -These rules operationalize **ISO/IEC 42001:2023** (AI Management System) — DevTrail's vertebral standard. Following them produces documented evidence compatible with: +StrayMark externalizes the cognitive discipline of senior software engineering — explicit scope, declared decisions, named risks, recorded alternatives, audited trails — into versioned files that live alongside the code. The intent is to constrain the agent's decision space so AI-assisted work stays coherent across many turns instead of drifting into hidden technical debt. +As a side effect of doing the engineering work this way, the artifacts produced map cleanly onto the major AI governance frameworks. The rules are written for the engineering work first; the compliance evidence is what falls out when the work is done with discipline. + +**Frameworks the resulting evidence aligns with:** + +- **ISO/IEC 42001:2023** (AI Management System) — vertebral standard for governance structure - **EU AI Act** (Regulation 2024/1689) — risk classification, transparency, incident reporting - **NIST AI RMF 1.0 + 600-1** — risk management functions and generative AI risk profiles - **GDPR** — data protection impact assessments and privacy safeguards -> See `AI-GOVERNANCE-POLICY.md` for the full ISO 42001 Annex A control mapping. +**Optional regional scope** — when `.straymark/config.yml` declares `regional_scope: china`, the framework additionally produces evidence for: + +- **TC260 AI Safety Governance Framework v2.0** — risk grading (TC260RA) +- **PIPL** (Personal Information Protection Law) — PIPIA, retention ≥ 3 years +- **GB 45438-2025** *(mandatory)* — AI-generated content labeling (AILABEL) +- **CAC Algorithm Filing** — algorithm registration (CACFILE) +- **GB/T 45652-2025** — pre-training & fine-tuning data security +- **CSL 2026** — cybersecurity incident reporting (1h / 4h+72h+30d windows) + +> See `AI-GOVERNANCE-POLICY.md` for the ISO 42001 Annex A control mapping and `CHINA-REGULATORY-FRAMEWORK.md` for the China coverage matrix. The product-level rationale lives in [`Propuesta/straymark-design-principles.md`](https://github.com/StrangeDaysTech/straymark/blob/main/Propuesta/straymark-design-principles.md). --- ## 1. Fundamental Principle -> **"No significant change without a documented trace."** +> **"No significant change without a documented trace — and a constrained decision space for the agent."** --- ## 2. Language Configuration -Check `.devtrail/config.yml` for the project's language setting: +Check `.straymark/config.yml` for the project's language setting: ```yaml -language: en # Options: en, es (default: en) +language: en # Options: en, es, zh-CN (default: en) ``` **Template paths based on language:** | Language | Template Path | |----------|---------------| -| `en` (default) | `.devtrail/templates/TEMPLATE-*.md` | -| `es` | `.devtrail/templates/i18n/es/TEMPLATE-*.md` | +| `en` (default) | `.straymark/templates/TEMPLATE-*.md` | +| `es` | `.straymark/templates/i18n/es/TEMPLATE-*.md` | +| `zh-CN` | `.straymark/templates/i18n/zh-CN/TEMPLATE-*.md` | If the config file doesn't exist or `language` is not set, use English (`en`) as default. @@ -48,24 +63,24 @@ If the config file doesn't exist or `language` is not set, use English (`en`) as ## 3. Documentation Reporting -At the end of each task, you MUST report your DevTrail documentation status: +At the end of each task, you MUST report your StrayMark documentation status: **If you created documentation:** ``` -DevTrail: Created AILOG-2025-01-27-001-implement-auth.md +StrayMark: Created AILOG-2025-01-27-001-implement-auth.md ``` **If documentation was not needed:** ``` -DevTrail: No documentation required (minor change / below complexity threshold) +StrayMark: No documentation required (minor change / below complexity threshold) ``` **If you should have documented but didn't:** ``` -DevTrail: Documentation pending - review required +StrayMark: Documentation pending - review required ``` -This transparency helps users verify compliance with DevTrail rules. +This transparency helps users verify compliance with StrayMark rules. --- @@ -116,7 +131,7 @@ git push -u origin fix/descriptive-name gh pr create --title "fix: description" --body "..." ``` -> **Full details:** `.devtrail/00-governance/GIT-BRANCHING-STRATEGY.md` +> **Full details:** `.straymark/00-governance/GIT-BRANCHING-STRATEGY.md` --- @@ -126,13 +141,15 @@ gh pr create --title "fix: description" --body "..." | Situation | Action | |-----------|--------| -| Code complexity above threshold | Create AILOG — run `devtrail analyze --output json`; fallback: >20 lines | +| Code complexity above threshold | Create AILOG — run `straymark analyze --output json`; fallback: >20 lines | | Decision between technical alternatives | Create AIDEC | | Changes in auth/authorization/PII | Create AILOG (`risk_level: high`) + ETH draft | | Changes in public API or DB schema | Create AILOG + consider ADR | | Changes in ML models or AI prompts | Create AILOG + human review | | Security-critical dependency changes | Create AILOG + human review | | OTel instrumentation changes | Create AILOG + tag `observabilidad` | +| Multi-session implementation block (>1 day, >5 tasks across phases) | Declare a **Charter** — `straymark charter new`. See section 15. | +| Transversal technical debt — heritage from prior Charter, applies to multiple modules, or requires dedicated Charter to remediate | Create **TDE** — distinct from per-Charter `R`. See `.straymark/00-governance/AGENT-RULES.md` §3 for TDE vs `R` disambiguation. | ### DO NOT DOCUMENT @@ -178,12 +195,12 @@ related: - Use **kebab-case** keywords: `sqlite`, `api-design`, `gnome-integration` - 3 to 8 tags per document — describe topic, technology, or component -- Tags enable search and categorization in `devtrail explore` +- Tags enable search and categorization in `straymark explore` ### Related -- Reference other **DevTrail documents** by filename (with `.md`): `AILOG-2025-01-27-001-implement-oauth.md` -- For documents in subdirectories, include path from `.devtrail/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-file.md` +- Reference other **StrayMark documents** by filename (with `.md`): `AILOG-2025-01-27-001-implement-oauth.md` +- For documents in subdirectories, include path from `.straymark/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-file.md` - For documents in the same directory, filename alone is sufficient - **Do not** use task IDs, issue numbers, or URLs — those go in the document body @@ -205,6 +222,11 @@ related: | **TES** | Propose | Validation | | **INC** | Contribute analysis | Conclusions | | **TDE** | Identify | Prioritize | +| **PIPIA** *(china)* | Create draft | Approval (always) | +| **CACFILE** *(china)* | Create draft | Approval (always — counsel + compliance officer before submission) | +| **TC260RA** *(china)* | Create draft | Approval (always) | +| **AILABEL** *(china)* | Create draft | Approval (always — before deployment) | +| **Charter** | Scaffold via `charter new`; fill scope, files, risks, tasks | Operator owns the *trigger* and lifecycle transitions (`declared` → `in-progress` → `closed`). See section 15. | --- @@ -214,7 +236,7 @@ related: > Not everything is loaded in this session, but any document can be accessed when needed. ``` -.devtrail/ +.straymark/ ├── 00-governance/ ← POLICIES AND RULES │ ├── PRINCIPLES.md # Project guiding principles │ ├── DOCUMENTATION-POLICY.md # Complete documentation policy @@ -248,16 +270,28 @@ related: │ │ └── [AILOG-*.md] │ ├── decisions/ # Agent decisions (AIDEC) │ │ └── [AIDEC-*.md] -│ └── ethical-reviews/ # Ethical reviews (ETH, DPIA) -│ └── [ETH-*.md] +│ ├── ethical-reviews/ # Ethical reviews (ETH, DPIA, PIPIA*) +│ │ └── [ETH-*.md] +│ ├── regulatory-filings/ # CAC algorithm filings (CACFILE*) +│ │ └── [CACFILE-*.md] +│ └── risk-assessments/ # TC260 risk assessments (TC260RA*) +│ └── [TC260RA-*.md] │ ├── 08-security/ ← SECURITY ASSESSMENTS (SEC) │ └── [SEC-*.md] │ ├── 09-ai-models/ ← AI MODEL CARDS (MCARD) -│ └── [MCARD-*.md] +│ ├── [MCARD-*.md] +│ └── labeling/ # GB 45438 content labeling plans (AILABEL*) +│ └── [AILABEL-*.md] +│ +├── charters/ ← CHARTERS — BOUNDED UNITS OF WORK +│ ├── [NN-slug.md] # Declarative ex-ante scope (filename: NN-slug.md, NOT TYPE-YYYY-...) +│ └── [NN-slug.telemetry.yaml] # Post-close telemetry (created by `straymark charter close`) │ -├── templates/ ← TEMPLATES (12 types) +├── templates/ ← TEMPLATES (12 base + 4 China* + Charter) + +* Only created when regional_scope: china is enabled in .straymark/config.yml. │ └── QUICK-REFERENCE.md ← 1-page quick reference ``` @@ -268,15 +302,19 @@ related: | Situation | Document to load | |-----------|------------------| -| Going to create an AILOG | `.devtrail/templates/TEMPLATE-AILOG.md` | -| Going to create an AIDEC | `.devtrail/templates/TEMPLATE-AIDEC.md` | -| Going to create an ADR | `.devtrail/templates/TEMPLATE-ADR.md` | -| Going to create a REQ | `.devtrail/templates/TEMPLATE-REQ.md` | -| Questions about naming or metadata | `.devtrail/00-governance/DOCUMENTATION-POLICY.md` | -| Questions about autonomy limits | `.devtrail/00-governance/AGENT-RULES.md` | -| Need to see existing requirements | List `.devtrail/01-requirements/` | -| Need to see existing ADRs | List `.devtrail/02-design/decisions/` | -| Need to see technical debt | List `.devtrail/06-evolution/technical-debt/` | +| Going to create an AILOG | `.straymark/templates/TEMPLATE-AILOG.md` | +| Going to create an AIDEC | `.straymark/templates/TEMPLATE-AIDEC.md` | +| Going to create an ADR | `.straymark/templates/TEMPLATE-ADR.md` | +| Going to create a REQ | `.straymark/templates/TEMPLATE-REQ.md` | +| Questions about naming or metadata | `.straymark/00-governance/DOCUMENTATION-POLICY.md` | +| Questions about autonomy limits | `.straymark/00-governance/AGENT-RULES.md` | +| Need to see existing requirements | List `.straymark/01-requirements/` | +| Need to see existing ADRs | List `.straymark/02-design/decisions/` | +| Need to see technical debt | List `.straymark/06-evolution/technical-debt/` | +| Going to declare a Charter | `.straymark/templates/charter/charter-template.md` (or `straymark charter new`) | +| Need to see existing Charters | `straymark charter list` (or list `.straymark/charters/`) | +| SpecKit user — when does a feature yield a Charter? | `.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md` | +| Wondering why agents surface things you didn't ask | `.straymark/00-governance/EMERGENT-OBSERVATION-DESIGN.md` | --- @@ -303,26 +341,27 @@ related: | Prefix | Name | Location | |--------|------|----------| -| `AILOG` | AI Action Log | `.devtrail/07-ai-audit/agent-logs/` | -| `AIDEC` | AI Decision | `.devtrail/07-ai-audit/decisions/` | -| `ETH` | Ethical Review | `.devtrail/07-ai-audit/ethical-reviews/` | -| `ADR` | Architecture Decision Record | `.devtrail/02-design/decisions/` | -| `REQ` | Requirement | `.devtrail/01-requirements/` | -| `TES` | Test Plan | `.devtrail/04-testing/` | -| `INC` | Incident Post-mortem | `.devtrail/05-operations/incidents/` | -| `TDE` | Technical Debt | `.devtrail/06-evolution/technical-debt/` | -| `SEC` | Security Assessment | `.devtrail/08-security/` | -| `MCARD` | Model/System Card | `.devtrail/09-ai-models/` | -| `SBOM` | Software Bill of Materials | `.devtrail/07-ai-audit/` | -| `DPIA` | Data Protection Impact Assessment | `.devtrail/07-ai-audit/ethical-reviews/` | +| `AILOG` | AI Action Log | `.straymark/07-ai-audit/agent-logs/` | +| `AIDEC` | AI Decision | `.straymark/07-ai-audit/decisions/` | +| `ETH` | Ethical Review | `.straymark/07-ai-audit/ethical-reviews/` | +| `ADR` | Architecture Decision Record | `.straymark/02-design/decisions/` | +| `REQ` | Requirement | `.straymark/01-requirements/` | +| `TES` | Test Plan | `.straymark/04-testing/` | +| `INC` | Incident Post-mortem | `.straymark/05-operations/incidents/` | +| `TDE` | Technical Debt | `.straymark/06-evolution/technical-debt/` | +| `SEC` | Security Assessment | `.straymark/08-security/` | +| `MCARD` | Model/System Card | `.straymark/09-ai-models/` | +| `SBOM` | Software Bill of Materials | `.straymark/07-ai-audit/` | +| `DPIA` | Data Protection Impact Assessment | `.straymark/07-ai-audit/ethical-reviews/` | +| `Charter` | Bounded unit of work (filename `NN-slug.md`, not `TYPE-YYYY-…`) | `.straymark/charters/` | --- ## 14. Regulatory Alignment -DevTrail is aligned with the following standards and regulations: +StrayMark is aligned with the following standards and regulations: -| Standard | Role in DevTrail | Key Documents | +| Standard | Role in StrayMark | Key Documents | |----------|-----------------|---------------| | **ISO/IEC 42001:2023** | Vertebral standard — AI Management System | AI-GOVERNANCE-POLICY.md | | **EU AI Act** | Risk classification, incident reporting, transparency | ETH, INC, AILOG regulatory fields | @@ -334,42 +373,108 @@ DevTrail is aligned with the following standards and regulations: | **OpenTelemetry** | Observability (optional, complementary) | Tag `observabilidad` | | **C4 Model** | Architecture visualization in ADR documents | ADR (Mermaid diagrams) | -> **Reference**: See `AI-GOVERNANCE-POLICY.md` for the full ISO 42001 Annex A mapping to DevTrail documents. +> **Reference**: See `AI-GOVERNANCE-POLICY.md` for the full ISO 42001 Annex A mapping to StrayMark documents. --- -## Directive Injection Markers +## 15. Charters — bounded units of work -DevTrail uses HTML comment markers to manage injected content in agent configuration files (CLAUDE.md, GEMINI.md, .cursorrules, etc.): +A **Charter** is StrayMark's artifact for an *implementation block that is too big to track as a single AILOG and too small to deserve its own product spec*. It pairs **declarative ex-ante scope** (files to modify, risks, tasks, effort estimate) with **ex-post telemetry** (drift detection, external audit, lessons learned). Concretely: the kind of work that takes >1 day, spans >5 tasks, or crosses multiple sessions where an agent might lose the thread. -```html - -... managed content ... - +Charters are **conceptually distinct** from the 12+4 document types listed in section 13: + +- They live at `.straymark/charters/NN-slug.md` (sequential prefix, not date-prefix). +- Their lifecycle is `declared` → `in-progress` → `closed`, persisted in frontmatter as the source of truth. +- Telemetry sits beside them as `NN-slug.telemetry.yaml`, written by `straymark charter close`. +- External audits resolve to `.straymark/audits/CHARTER-NN/` and merge back into telemetry. + +### When to declare a Charter + +Trigger row in section 6 names the heuristic; expanded: + +- The work spans **more than one working session** and you need a stable scope contract you can drift-check at close. +- The work has **5+ named tasks** with a topological order (e.g., a SpecKit `tasks.md`). +- The work warrants **external audit** at completion (cross-model review, cross-team review). +- You want **measurable telemetry**: time-to-close, drift count, lessons that feed forward. + +### Charter lifecycle + +| Stage | What happens | CLI | +|-------|--------------|-----| +| **Declared** | Operator scaffolds Charter, fills scope/files/risks/tasks. Status `declared`. | `straymark charter new` | +| **In progress** | Operator flips status to `in-progress` when execution starts. Day-to-day work continues to produce AILOGs. | (manual frontmatter edit) | +| **Batch update** *(multi-batch only, fw-4.14.0+)* | For Charters spanning 3+ batches or >1 day, the AILOG carries a `## Batch Ledger` with one `### Batch N` entry per batch starting as `(pending)`. After each batch commit lands, fill the entry **before pushing** so the AILOG update and the work ride the same push. Single-batch Charters skip this step entirely. | `straymark charter batch-complete CHARTER-NN ` | +| **Drift check** | Before closing, verify declared files vs. actual git diff. AILOG-suppressed paths are noise-filtered; pending `### Batch N` entries cause a hard fail (`--no-batch-ledger-check` bypasses). | `straymark charter drift` | +| **External audit** *(optional)* | Generate prompt → run N auditor CLIs → consolidate → merge into telemetry. | `straymark charter audit` + `/straymark-audit-prompt` + `/straymark-audit-execute` + `/straymark-audit-review` | +| **Closed** | Telemetry yaml emitted; status flips to `closed`; charter is now an audit artifact. | `straymark charter close` | + +### How Charters relate to existing artifacts + +- A Charter **does not replace** AILOGs. AILOGs document individual blocks of code work; the Charter wraps them as a unit. `originating_ailogs:` in the Charter frontmatter declares which AILOGs the Charter contains. +- A Charter **does not replace** ADRs. ADRs document architectural decisions; a Charter may reference them in `originating_spec` or in body sections. +- A Charter **bridges SpecKit features** (`specs/NNN-feature/spec.md`) and execution. See `.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md` for granularity heuristics and creation timing. + +### Quick CLI surface + +```bash +straymark charter new # scaffold a Charter (interactive) +straymark charter list # enumerate Charters with status/effort/origin +straymark charter status CHARTER-NN # detailed view of one Charter +straymark charter drift CHARTER-NN # file-vs-commit drift, AILOG-aware + Batch Ledger gate +straymark charter batch-complete CHARTER-NN # fill AILOG `## Batch Ledger` Batch (multi-batch only) +straymark charter audit CHARTER-NN # multi-model external audit (orchestration only) +straymark charter close CHARTER-NN # record telemetry; flip status to `closed` +straymark charter refresh-suggest # SpecKit refresh recommendation (chain-level, fw-4.16.0+) — see §15.A +straymark charter amend CHARTER-NN # scaffold post-close Batch N.4 amendment (fw-4.16.0+) — see §15.B ``` -- Content between these markers is managed by `devtrail init`, `update`, and `repair` -- Do not remove or modify these markers manually — they are required for safe updates -- If markers are missing from a target file, DevTrail appends the content block at the end +> **Schema**: `.straymark/schemas/charter.schema.v0.json` (declarative) and `.straymark/schemas/charter-telemetry.schema.v0.json` (telemetry). Both are experimental v0 — patterns crystallize after validation against a second domain (Principle #12). ---- +### §15.A — Pre-declare SpecKit refresh *(fw-4.16.0+)* -*DevTrail | [GitHub](https://github.com/StrangeDaysTech/devtrail)* -*[Strange Days Tech](https://strangedays.tech) — Because every change tells a story.* - +Multi-Charter modules accumulate spec drift over time. After 3+ Charters in a chain, SpecKit artifacts (`plan.md`, `data-model.md`, `contracts/*`, `quickstart.md`, `research.md`) authored at chain start tend to lag behind the implementation. The fix is a dedicated **refresh PR** between Charter-N close and Charter-(N+1) declare that integrates accumulated learnings into `research.md` (categorized buckets: reusable patterns, code gaps, discipline patterns, empirical corrections) and ratifies operator decisions. The next Charter's `## Context` cites each learning by id. + +**Trigger heuristic** — adopt when (a) chain length ≥ 3 closed Charters in the module AND (b) rolling mean of `agent_quality.r_n_plus_one_emergent_count` across last 3 > 6 AND (c) no refresh PR landed since the chain's branch point. Run: + +```bash +straymark charter refresh-suggest # read-only — prints recommendation +``` + +**Telemetry** — `charter_telemetry.pre_declare_refresh:` (optional, opt-in). See `.straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md` Pattern 1 for full mechanics. + +### §15.B — Post-close audit-driven amendment (Batch N.4) *(fw-4.16.0+)* + +External audit cycles run post-close. When Critical or High findings arrive after a Charter has been marked `status: closed`, the bounded remediation pattern is a **Batch N.4 amendment** that rides on the same execute branch: a new AILOG documents the amendment, the original AILOG receives a `## Historical correction` subsection pointing forward, and the telemetry gains a `post_close_amendment:` block. Apply only when (a) findings are Critical/High, (b) the Charter's closure criterion is materially unmet, AND (c) the fix surface fits in one cohesive PR (~< 25 files, no architectural reopen). Larger or architectural fixes warrant a new Charter. + +```bash +straymark charter amend CHARTER-NN \ # scaffolds the new AILOG, edits the original, prints YAML + --trigger external_audit \ + --findings-closed 5 \ + --ailog-title "post-close remediation — DI wiring + retry" +``` -## DevTrail Documentation Rules +The command does not touch git — the operator decides when to commit. The `straymark charter audit --merge-reports --merge-into ` path tolerates `external_audit: []` placeholders in v0.2+ schema so the round-trip with `post_close_amendment` is smooth. See `.straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md` Pattern 2 for full mechanics. -Identity: Use `cursor-v{version}` in the `agent:` field. +--- -Document when: complex code — run `devtrail analyze --output json`, AILOG if `above_threshold > 0` (fallback: >20 lines), alternatives (AIDEC), auth/PII (AILOG+ETH), API/DB changes (AILOG+ADR), ML/prompts (AILOG+review). +## Directive Injection Markers -Review required: ETH, ADR, SEC, MCARD, DPIA → always. risk_level high/critical → always. +StrayMark uses HTML comment markers to manage injected content in agent configuration files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.cursorrules`, `.cursor/rules/straymark.md`): -Never document: credentials, tokens, API keys, PII. +```html + +... managed content ... + +``` -Regulatory fields (when relevant): eu_ai_act_risk, nist_genai_risks, iso_42001_clause. +- Content between these markers is managed by `straymark init`, `update`, and `repair` +- Do not remove or modify these markers manually — they are required for safe updates +- If markers are missing from a target file, StrayMark appends the content block at the end +- **Missing-target behavior** *(refined in fw-4.16.2 / cli-3.14.1)*: `straymark init`, `straymark update-framework`, and `straymark repair` all walk `dist-manifest.yml::injections:` and **create any missing target file** (with the marker block) per individual target — a single deleted directive file like `AGENTS.md` is restored without needing to re-run init or remove anything else. There is no opt-out per target short of editing the manifest. *(Historical note: through `cli-3.14.0` / `fw-4.16.1`, `straymark repair` was gated on `STRAYMARK.md` being absent and would silently skip a per-target restore; that gate was removed in `cli-3.14.1`.)* +- `AGENTS.md` is the open standard donated to the Agentic AI Foundation (Linux Foundation, 2025) and is read by Claude Code, OpenAI Codex CLI, Cursor, Aider, Devin, Sourcegraph Amp, Google Jules, Zed AI, Continue, Roo Code, Factory Droids, GitHub Copilot, Gemini CLI, Windsurf, Amazon Q and others. CLI-specific files (`CLAUDE.md`, `GEMINI.md`, etc.) coexist with `AGENTS.md` and provide platform-specific identity strings. -Observability: No PII in OTel attributes. Tag instrumentation changes with `observabilidad`. +--- -Naming: [TYPE]-[YYYY-MM-DD]-[NNN]-[description].md +*StrayMark | [GitHub](https://github.com/StrangeDaysTech/straymark)* +*[Strange Days Tech](https://strangedays.tech) — Because every change tells a story.* + diff --git a/.devtrail/.checksums.json b/.devtrail/.checksums.json deleted file mode 100644 index 95e4b02..0000000 --- a/.devtrail/.checksums.json +++ /dev/null @@ -1,81 +0,0 @@ -{ - "version": "fw-4.1.0", - "files": { - ".devtrail/templates/TEMPLATE-SBOM.md": "f057f9f047947168a837945e5895989154d28a6a9c67fd002d161e771908996d", - ".devtrail/templates/i18n/es/TEMPLATE-TDE.md": "2ef5d2f477648fa86bda4133c1f56546468564736bde0f53d9ed1efe5aff565f", - ".devtrail/templates/TEMPLATE-AILOG.md": "db450fc1707acf1863ee55f72774904304d84cc5a095427a9647c4e18a6f1353", - ".devtrail/03-implementation/i18n/es/NIST-AI-RMF-MANAGE-GUIDE.md": "609ee5739d5fc6315044879d69b384a408ad59797aa5b77b4285e2281cd6cddc", - ".devtrail/templates/i18n/es/TEMPLATE-TES.md": "010e7eabf5d5ca79041e139c533dc77cb86df2b67b6d1627b86615bc83386042", - ".devtrail/config.yml": "f718f0be6395ac9b7cdb6b34fb535b06a44ceae6bc9aedecd653950980e69ae0", - ".devtrail/templates/TEMPLATE-MCARD.md": "5df5089d3c22c216fbccbced31aec04207e2d57c31b02074ddf72c07d2c5f7d8", - ".devtrail/templates/TEMPLATE-TDE.md": "9cf4ae0342d166a47e702548f4fdc08600de1ba9658d47f593bfb825ee599398", - ".devtrail/00-governance/AGENT-RULES.md": "065dd12351dc709b269818db5e97b44f87c45f25e5f9118994df98136eccb29b", - ".devtrail/00-governance/ISO-25010-2023-REFERENCE.md": "9c732fef6de459474f5284f5e9605830332cf08abd0f316474aa5fbcbdf3ce5d", - ".devtrail/00-governance/QUICK-REFERENCE.md": "3ec940069fdd5beb1e9924a17f3976ff7744cf33fca1fc58d8c9d436646ff176", - ".devtrail/03-implementation/.gitkeep": "6f47b5c66f0e61dc78e4e57f7a4d858336bdc3866f3a26a397f3e2a1869810c0", - ".devtrail/00-governance/AI-KPIS.md": "e7cdbb14d083244249ede69448cfad36697309dd99d587acd72d5afb83a4f3dd", - ".devtrail/00-governance/i18n/es/OBSERVABILITY-GUIDE.md": "02e9776c9576f30498d4b255abdc9cf2e398625054e36d558e8a938ddad569ea", - ".devtrail/09-ai-models/.gitkeep": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", - ".devtrail/templates/i18n/es/TEMPLATE-AILOG.md": "22e2e419cb377d50c0c09cb9f4f67e4073cd42f357fd842486cfa80873d954b1", - ".devtrail/00-governance/i18n/es/AGENT-RULES.md": "ea9b5cda62c8886b78e2356be76908a78f905cc87fffcdc8bcff92f1da8c8c25", - ".devtrail/00-governance/i18n/es/QUICK-REFERENCE.md": "2967e175a0601415c477c3b8fe9a89c71850b45d0a9d6096dfb9097276d5258b", - ".devtrail/00-governance/DOCUMENTATION-POLICY.md": "5e843ecf25e9040dfa93ba9a0efc30167909c51b0b8869e300ab370766d571b0", - ".devtrail/07-ai-audit/ethical-reviews/.gitkeep": "a300a8f3c231fbb98a5e04e3165ef8b3f4fe5af9cc7f77467c26244194ce0d45", - ".devtrail/02-design/decisions/.gitkeep": "d268c27da8232243534ae5dbcbfc52629f1112c2bfc018462a41fbe1a233b164", - ".devtrail/03-implementation/i18n/es/NIST-AI-600-1-GENAI-RISKS.md": "eddf4fc5d6f55200c4860812e24263f1353428b9849bad6ae1edff12db85a6ad", - ".devtrail/03-implementation/i18n/es/NIST-AI-RMF-MAP-GUIDE.md": "8e3e2a7a4020162cd5aa394f06ad196663b2595bf0ed2313e2445ac51bfb4540", - ".devtrail/QUICK-REFERENCE.md": "f44f238574534268398a83f1c4902a56ba64da4ba50054c6caef51ed0723552e", - ".devtrail/templates/i18n/es/TEMPLATE-AIDEC.md": "6f310a73dce8d1ec2643f6d727a630f31dba5a99c4bdb5757c7602a30faaca56", - ".devtrail/templates/i18n/es/TEMPLATE-ETH.md": "0515802f1bb8a20c7b4ddc504f9a80941e3c35910a239d37f4cf30c430e72058", - ".devtrail/00-governance/i18n/es/AI-RISK-CATALOG.md": "dda45ff0658dab1d9650162bec0b20e386d4a8fda4be29afe7ca0f7c67c80ea8", - ".devtrail/00-governance/MANAGEMENT-REVIEW-TEMPLATE.md": "f6f2675fcf7b1f54c80393245274344ce0195a3cf7dadebef374c6db6e903f17", - ".devtrail/00-governance/i18n/es/AI-GOVERNANCE-POLICY.md": "11bd4ebd2841926b5ca9e983abaf8bf41809fc335462f9b69a3b2132e6b04172", - ".devtrail/templates/TEMPLATE-ADR.md": "ab96076303fed166f300dd44b696657ffb5787edcba2eee1970f26966d1897e4", - ".devtrail/00-governance/i18n/es/GIT-BRANCHING-STRATEGY.md": "ec6794dd8ced6ddd617d6769821aad0e5e697b2ffb25a6e46c2d4208f0e57b51", - ".devtrail/00-governance/i18n/es/AI-LIFECYCLE-TRACKER.md": "c7e5e8b8969d4a91ee11d01dffef81887473822c690a8de3283672da61de00b1", - ".devtrail/templates/i18n/es/TEMPLATE-INC.md": "f6a26ab96f33a161267bf610438dbf77f792b218b700ab027538d0f95904d4e2", - ".devtrail/templates/TEMPLATE-SEC.md": "901769daf47bee53d854cce0dbc0cd9cd257ddf473768a70bfdf4464713c18d0", - ".devtrail/00-governance/AI-GOVERNANCE-POLICY.md": "08439c90ab511e1132fff083b2f8d1f6db8146450140b87a9839ddd8dc411a10", - ".devtrail/00-governance/AI-LIFECYCLE-TRACKER.md": "d8769719ef59f794c0fcf6ea50a4b8dad46fd8d5e60ecfc852479b45a50e51da", - ".devtrail/00-governance/OBSERVABILITY-GUIDE.md": "b6e57c2015cfb385d5e7634b64d36c6220d082c5cc912b13ac5768c500d5e89f", - ".devtrail/03-implementation/i18n/es/NIST-AI-RMF-GOVERN-GUIDE.md": "8bc6b011d13ecd0cd68d36975fb29552b2b59de75cb6164711347f0679012a8e", - ".devtrail/templates/i18n/es/TEMPLATE-REQ.md": "2205f16656de85f8a8995785836be66ffc5c5472dc66f27f93ac09e423817e48", - ".devtrail/05-operations/incidents/.gitkeep": "a0face4379a29d0f518afeb57eb4a1e6f1b6025d38ca02b06ee0fac6febfdfdc", - ".devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md": "2e2334a90e5338307455f35ef75f60e65d17717df46744ce385090fd88241ba0", - ".devtrail/00-governance/i18n/es/MANAGEMENT-REVIEW-TEMPLATE.md": "8bc6ae3a42a1588c253320db061ae0c7c8b7cd5dc80e05bd3b99808d833cf2ee", - ".devtrail/03-implementation/NIST-AI-RMF-GOVERN-GUIDE.md": "630c0727c9cabf7ae5156ed5e0e68925b6cc58cd20bca923b4a56f6b95e1980d", - ".devtrail/00-governance/i18n/es/AI-KPIS.md": "fbcb819e2d169416fe9b4c2eddffcec933c7545f8789e4da2d0b86ab16aa7f4a", - ".devtrail/07-ai-audit/agent-logs/.gitkeep": "9f44184239ba322e5771ca92e19e789d0dcd4d59475e2474fdb7bb5eff99048f", - ".devtrail/08-security/.gitkeep": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", - ".devtrail/00-governance/AI-RISK-CATALOG.md": "d2d29b8a687da085c086a1384763b502b69a6294c5ab68aab1db3bec732605f8", - ".devtrail/templates/i18n/es/TEMPLATE-MCARD.md": "694388a4691d494f837ee36ce6b09b1461b2455129a4c3f1bc90097109ea8fda", - ".devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md": "01b9855d01205b5b5085822d291d83cf7681b8cd78c0c2f60754d33452ed7f1c", - ".devtrail/00-governance/GIT-BRANCHING-STRATEGY.md": "c0fbd6e48cbcf494265d61e96e34bccd64b3ca714708b8309a6b1d7db4d226a5", - ".devtrail/00-governance/i18n/es/PRINCIPLES.md": "2255e2e235739ad95e6ff7814009d12fe1adc48958d7afee8ff776eb8b6aa856", - ".devtrail/templates/TEMPLATE-TES.md": "d25b73da60a1bddd98db1c58c4845a4ef0d748b1732fe47c71c61d5985072621", - ".devtrail/templates/TEMPLATE-REQ.md": "4ab848dac065e8ed93bbd1392e96cdc6551802d61513d69ea414e05e8fca1029", - ".devtrail/templates/i18n/es/TEMPLATE-SBOM.md": "ce32f21fc69c557b4aa944d11eb346c52a88f7396de288f73df88e6a25b8c8ed", - ".devtrail/03-implementation/NIST-AI-600-1-GENAI-RISKS.md": "1e38f34e7863a43a524c2ae3fafea5784fd4ce849f274767c9bed412710d27ee", - ".devtrail/06-evolution/technical-debt/.gitkeep": "a1e8aa0b06407e59dee1a6f3f52e47a6044aeca3fcc2a2108c853cb775428a6a", - ".devtrail/00-governance/C4-DIAGRAM-GUIDE.md": "39d71769ff9738f84c4ad9800fdde338394d9c144b1bd5e2ade2562fa15ffa74", - ".devtrail/templates/TEMPLATE-DPIA.md": "06ec15eebe71dd14fa36edbf2b8fecf43a4820e9db1dc7bf136ab1f48803c7aa", - ".devtrail/05-operations/runbooks/.gitkeep": "165100a8abe03040590c2ee3b051950527bf0250f8c5febaf529a27089751bc3", - ".devtrail/templates/i18n/es/TEMPLATE-DPIA.md": "eecc86b0bf580b5f46b8167b9e948e2f1ca53f5625de0e49c3fc403489b1e728", - ".devtrail/templates/i18n/es/TEMPLATE-SEC.md": "6f42a2df4472271a25265272757f6e438f3928122a7109d22249f98dd71392a0", - ".devtrail/03-implementation/i18n/es/NIST-AI-RMF-MEASURE-GUIDE.md": "8d7d295aec1028c3777a4a9e7346ca0106f6c1a7645575d3b99fb49f222dae60", - ".devtrail/01-requirements/.gitkeep": "b87527d29d1ec75b950d6b5fcdac2063a5426486c2cabee43841e1fb2780190c", - ".devtrail/00-governance/exceptions/.gitkeep": "b4aaf3d190e7dc76189a91d721842a6b74aa9aa9fcb5619ce0d1c5a16f60bf6d", - ".devtrail/templates/TEMPLATE-ETH.md": "a5c13b393b65750dfa67fcb8bdedebbed84be335ec6abbc73600f7a46404501c", - ".devtrail/03-implementation/NIST-AI-RMF-MAP-GUIDE.md": "03ca6724017116e3e044a5545b0bf682c18103ea1f09c6761ba54e9cec466408", - ".devtrail/templates/TEMPLATE-AIDEC.md": "18aa0d6da2dc4fc3fa1809ad4f1fbd75751f14c8b7fc888b7e5daff96ecd87e5", - ".devtrail/templates/TEMPLATE-INC.md": "4f6a50748f5fb008228884e941f469f31829c304c1181dd6eb78ed4b6870d821", - "DEVTRAIL.md": "329a3971f9ebdce63b0b9eeb68be4cce0d51fa5dde08ba825cdd74297590b6d1", - ".devtrail/04-testing/.gitkeep": "1d8198124b57687ba4120fc888f855ffa707c93113d54d3c46c77f5152bd430f", - ".devtrail/03-implementation/NIST-AI-RMF-MEASURE-GUIDE.md": "175244d98c724a5ebbb97e822c68f0a334685089aaf92924f53f7750524d5b38", - ".devtrail/03-implementation/NIST-AI-RMF-MANAGE-GUIDE.md": "327add87f44ebcf45842fc3ac170cc8de8387c0690e9370ab9c32f4ff965591c", - ".devtrail/00-governance/PRINCIPLES.md": "fb6bf7276b65b3a30bfba5432fb13702d20aac5730db681ed7e51beadaa2d4cc", - ".devtrail/dist-manifest.yml": "d5f87de6ec0afa62980f11bdf1a6e39a4e941374208d65f9b14e266680c1bdb4", - ".devtrail/07-ai-audit/decisions/.gitkeep": "c7c86a6c44e638da00088beeca6797a11ecdd84dafbaae6210905cc86a13486f", - ".devtrail/templates/i18n/es/TEMPLATE-ADR.md": "19b5747fd28e16cd4234d16b9814f88eb5c0445f726259be500001182176fedb" - } -} \ No newline at end of file diff --git a/.devtrail/00-governance/AGENT-RULES.md b/.devtrail/00-governance/AGENT-RULES.md deleted file mode 100644 index 8255548..0000000 --- a/.devtrail/00-governance/AGENT-RULES.md +++ /dev/null @@ -1,271 +0,0 @@ -# Rules for AI Agents - DevTrail - -> This document defines the rules that all AI agents must follow when working on projects under DevTrail. - ---- - -## 1. Mandatory Identification - -### When Starting a Session - -Every agent must identify themselves with: -- Agent name (e.g.: `claude-code-v1.0`, `cursor-v1.0`, `gemini-cli-v1.0`) -- Agent version if available - -### In Every Document - -Include in the frontmatter: -```yaml -agent: agent-name-v1.0 -confidence: high | medium | low -``` - ---- - -## 2. When to Document - -### MANDATORY - Create document - -| Situation | Type | Notes | -|-----------|------|-------| -| Code complexity above threshold | AILOG | Run `devtrail analyze --output json`. If `summary.above_threshold > 0`, create AILOG (default threshold: 8). **Fallback**: if CLI unavailable, apply >20 lines of business logic heuristic | -| Decision between 2+ technical alternatives | AIDEC | Document alternatives | -| Changes in auth/authorization/PII | AILOG + ETH | `risk_level: high`, ETH requires approval | -| Changes in public API or DB schema | AILOG | `risk_level: medium+`, consider ADR | -| Changes in ML models or AI prompts | AILOG | `risk_level: medium+`, human review required | -| Integration with external service | AILOG | - | -| Addition/removal/upgrade of security-critical dependencies | AILOG | Human review required | -| Changes affecting AI system lifecycle (deployment, retirement) | AILOG + ADR | Human review required | -| Changes to OTel instrumentation (spans, attributes, pipeline) | AILOG | Tag `observabilidad`, see §9 | - -### PROHIBITED - Do not document - -- Credentials, tokens, API keys -- Personally identifiable information -- Secrets of any kind - -### OPTIONAL - Does not require document - -- Formatting changes (whitespace, indentation) -- Typo corrections -- Code comments -- Minor style changes - ---- - -## 3. Autonomy Limits - -### Create Freely - -| Type | Description | -|------|-------------| -| AILOG | Logs of actions performed | -| AIDEC | Technical decisions made | - -### Create Draft → Requires Human Approval - -| Type | Description | -|------|-------------| -| ETH | Ethical reviews | -| ADR | Architectural decisions | - -### Propose → Requires Human Validation - -| Type | Description | -|------|-------------| -| REQ | System requirements | -| TES | Test plans | - -### Create Draft → Requires Human Approval (new types) - -| Type | Description | -|------|-------------| -| SEC | Security assessments (`review_required: true` always) | -| MCARD | Model/System cards (`review_required: true` always) | -| DPIA | Data Protection Impact Assessments (`review_required: true` always) | - -### Create Freely (new types) - -| Type | Description | -|------|-------------| -| SBOM | Software Bill of Materials (factual inventory) | - -### Identify Only → Human Prioritizes - -| Type | Description | -|------|-------------| -| TDE | Technical debt | -| INC | Incident conclusions | - ---- - -## 4. When to Request Human Review - -Mark `review_required: true` when: - -1. **Low confidence**: `confidence: low` -2. **High risk**: `risk_level: high | critical` -3. **Security decisions**: Any change in auth/authz -4. **Irreversible changes**: Migrations, deletions -5. **User impact**: Changes affecting UX -6. **Ethical concerns**: Privacy, bias, accessibility -7. **ML model changes**: Changes to model parameters, architecture, or training data -8. **AI prompt changes**: Modifications to prompts or agent instructions -9. **Security-critical dependencies**: Addition, removal, or upgrade of security-sensitive packages -10. **AI lifecycle changes**: Deployment, retirement, or major version changes of AI systems - ---- - -## 5. Document Format - -### Use Templates - -Before creating a document, load the corresponding template: - -``` -.devtrail/templates/TEMPLATE-[TYPE].md -``` - -### Naming Convention - -``` -[TYPE]-[YYYY-MM-DD]-[NNN]-[description].md -``` - -### Location - -| Type | Folder | -|------|--------| -| AILOG | `.devtrail/07-ai-audit/agent-logs/` | -| AIDEC | `.devtrail/07-ai-audit/decisions/` | -| ETH | `.devtrail/07-ai-audit/ethical-reviews/` | -| ADR | `.devtrail/02-design/decisions/` | -| REQ | `.devtrail/01-requirements/` | -| TES | `.devtrail/04-testing/` | -| INC | `.devtrail/05-operations/incidents/` | -| TDE | `.devtrail/06-evolution/technical-debt/` | -| SEC | `.devtrail/08-security/` | -| MCARD | `.devtrail/09-ai-models/` | -| SBOM | `.devtrail/07-ai-audit/` | -| DPIA | `.devtrail/07-ai-audit/ethical-reviews/` | - -### Tags and Related - -When populating the `tags` and `related` fields in frontmatter: - -**Tags:** -- Use kebab-case keywords: `sqlite`, `api-design`, `gnome-integration` -- 3 to 8 tags per document describing topic, technology, or component -- Tags enable search and categorization in `devtrail explore` - -**Related:** -- Reference other **DevTrail documents only** — use the document filename with `.md` extension -- If the document is in a subdirectory within `.devtrail/`, include the relative path: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-file.md` -- If the document is in the same directory, the filename alone is sufficient -- **Do not** put task IDs (T001, US3), issue numbers, or external URLs in `related` — put those in the document body instead - ---- - -## 6. Communication with Humans - -### Be Transparent - -- Explain the reasoning behind decisions -- Document considered alternatives -- Admit uncertainty when it exists - -### Be Concise - -- Get to the point -- Avoid unnecessary jargon -- Use lists and tables when appropriate - -### Be Proactive - -- Identify potential risks -- Suggest improvements when evident -- Alert about technical debt - ---- - -## 7. Error Handling - -If the agent makes an error: - -1. **Document** the error in an AILOG -2. **Explain** what went wrong -3. **Propose** correction -4. **Mark** `review_required: true` - ---- - -## 8. Document Updates - -### Create New vs Update - -| Situation | Action | -|-----------|--------| -| Minor correction | Update existing document | -| Significant change | Create new document | -| Obsolete document | Mark as `deprecated` | -| Complete replacement | Create new + mark previous as `superseded` | - -### When Updating - -- Update the `updated` field in frontmatter -- Add a note in the history section if it exists -- Maintain consistency with related documents - ---- - -## 9. Observability (OpenTelemetry) - -When working on projects that use OpenTelemetry: - -### Rules - -- **Do not** capture PII, tokens, or secrets in OTel attributes or logs -- **Record** instrumentation pipeline changes (new spans, changed attributes, Collector configuration) in AILOG with tag `observabilidad` -- **Create** AIDEC or ADR when adopting OTel in distributed projects — document the adoption decision and backend selection -- **Set** `observability_scope` in frontmatter when the change involves OTel instrumentation - -### Documentation Triggers - -| Change | Document | Additional | -|--------|----------|-----------| -| New spans or changed attributes | AILOG | Tag `observabilidad` | -| OTel backend selection | AIDEC or ADR | If distributed system | -| Collector pipeline configuration | AILOG | Tag `observabilidad` | -| Sampling strategy changes | AIDEC | Document rationale | -| Observability requirements | REQ | Use Observability Requirements section | -| Trace propagation tests | TES | Use Observability Tests section | -| Incident with trace evidence | INC | Include trace_id/span_id in timeline | -| Instrumentation debt | TDE | Tag `observabilidad` | - ---- - -## 10. Architecture Diagrams (C4 Model) - -When creating ADR documents that involve architectural changes: - -- **Include** a Mermaid C4 diagram at the appropriate level -- **Use** `C4Context` for system-level decisions (who uses the system, external dependencies) -- **Use** `C4Container` for service/container-level decisions (applications, databases, message queues) -- **Use** `C4Component` for internal module decisions (components within a service) -- **See** `00-governance/C4-DIAGRAM-GUIDE.md` for syntax reference and examples - -> Diagrams are optional for minor decisions. Use them when the decision changes system boundaries, introduces new services, or modifies inter-service communication. - ---- - -## 11. API Specification Tracking - -When a change modifies API endpoints: - -- **Verify** that the corresponding OpenAPI or AsyncAPI specification is updated -- **Reference** the spec path in the AILOG or ADR using the `api_spec_path` field (in REQ) or `api_changes` field (in ADR) -- **Document** breaking API changes in an ADR with `risk_level: high` - ---- - -*DevTrail v4.1.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.devtrail/00-governance/i18n/es/AGENT-RULES.md b/.devtrail/00-governance/i18n/es/AGENT-RULES.md deleted file mode 100644 index 5946d77..0000000 --- a/.devtrail/00-governance/i18n/es/AGENT-RULES.md +++ /dev/null @@ -1,273 +0,0 @@ -# Reglas para Agentes IA - DevTrail - -> Este documento define las reglas que todos los agentes de IA deben seguir cuando trabajan en proyectos bajo DevTrail. - -**Idiomas**: [English](../../AGENT-RULES.md) | Español - ---- - -## 1. Identificación Obligatoria - -### Al Iniciar una Sesión - -Cada agente debe identificarse con: -- Nombre del agente (ej.: `claude-code-v1.0`, `cursor-v1.0`, `gemini-cli-v1.0`) -- Versión del agente si está disponible - -### En Cada Documento - -Incluir en el frontmatter: -```yaml -agent: agent-name-v1.0 -confidence: high | medium | low -``` - ---- - -## 2. Cuándo Documentar - -### OBLIGATORIO - Crear documento - -| Situación | Tipo | Notas | -|-----------|------|-------| -| Complejidad de código sobre el umbral | AILOG | Ejecutar `devtrail analyze --output json`. Si `summary.above_threshold > 0`, crear AILOG (umbral por defecto: 8). **Alternativa**: si el CLI no está disponible, usar heurística de >20 líneas de lógica de negocio | -| Decisión entre 2+ alternativas técnicas | AIDEC | Documentar alternativas | -| Cambios en auth/autorización/PII | AILOG + ETH | `risk_level: high`, ETH requiere aprobación | -| Cambios en API pública o esquema de BD | AILOG | `risk_level: medium+`, considerar ADR | -| Cambios en modelos ML o prompts de IA | AILOG | `risk_level: medium+`, revisión humana requerida | -| Integración con servicio externo | AILOG | - | -| Adición/eliminación/actualización de dependencias críticas de seguridad | AILOG | Revisión humana requerida | -| Cambios que afectan el ciclo de vida del sistema de IA (despliegue, retirada) | AILOG + ADR | Revisión humana requerida | -| Cambios en instrumentación OTel (spans, atributos, pipeline) | AILOG | Tag `observabilidad`, ver §9 | - -### PROHIBIDO - No documentar - -- Credenciales, tokens, API keys -- Información personal identificable -- Secretos de cualquier tipo - -### OPCIONAL - No requiere documento - -- Cambios de formato (espacios, indentación) -- Correcciones de erratas -- Comentarios de código -- Cambios menores de estilo - ---- - -## 3. Límites de Autonomía - -### Crear Libremente - -| Tipo | Descripción | -|------|-------------| -| AILOG | Logs de acciones realizadas | -| AIDEC | Decisiones técnicas tomadas | - -### Crear Borrador → Requiere Aprobación Humana - -| Tipo | Descripción | -|------|-------------| -| ETH | Revisiones éticas | -| ADR | Decisiones arquitectónicas | - -### Proponer → Requiere Validación Humana - -| Tipo | Descripción | -|------|-------------| -| REQ | Requisitos del sistema | -| TES | Planes de prueba | - -### Crear Borrador → Requiere Aprobación Humana (tipos nuevos) - -| Tipo | Descripción | -|------|-------------| -| SEC | Evaluaciones de seguridad (`review_required: true` siempre) | -| MCARD | Tarjetas de modelo/sistema (`review_required: true` siempre) | -| DPIA | Evaluaciones de impacto en protección de datos (`review_required: true` siempre) | - -### Crear Libremente (tipos nuevos) - -| Tipo | Descripción | -|------|-------------| -| SBOM | Lista de materiales de software (inventario factual) | - -### Solo Identificar → Humano Prioriza - -| Tipo | Descripción | -|------|-------------| -| TDE | Deuda técnica | -| INC | Conclusiones de incidentes | - ---- - -## 4. Cuándo Solicitar Revisión Humana - -Marcar `review_required: true` cuando: - -1. **Baja confianza**: `confidence: low` -2. **Alto riesgo**: `risk_level: high | critical` -3. **Decisiones de seguridad**: Cualquier cambio en auth/authz -4. **Cambios irreversibles**: Migraciones, eliminaciones -5. **Impacto en usuarios**: Cambios que afectan UX -6. **Preocupaciones éticas**: Privacidad, sesgo, accesibilidad -7. **Cambios en modelos ML**: Cambios en parámetros del modelo, arquitectura o datos de entrenamiento -8. **Cambios en prompts de IA**: Modificaciones a prompts o instrucciones de agentes -9. **Dependencias críticas de seguridad**: Adición, eliminación o actualización de paquetes sensibles a la seguridad -10. **Cambios en ciclo de vida de IA**: Despliegue, retirada o cambios de versión mayor de sistemas de IA - ---- - -## 5. Formato de Documentos - -### Usar Plantillas - -Antes de crear un documento, cargar la plantilla correspondiente: - -``` -.devtrail/templates/TEMPLATE-[TIPO].md -``` - -### Convención de Nomenclatura - -``` -[TIPO]-[YYYY-MM-DD]-[NNN]-[descripcion].md -``` - -### Ubicación - -| Tipo | Carpeta | -|------|---------| -| AILOG | `.devtrail/07-ai-audit/agent-logs/` | -| AIDEC | `.devtrail/07-ai-audit/decisions/` | -| ETH | `.devtrail/07-ai-audit/ethical-reviews/` | -| ADR | `.devtrail/02-design/decisions/` | -| REQ | `.devtrail/01-requirements/` | -| TES | `.devtrail/04-testing/` | -| INC | `.devtrail/05-operations/incidents/` | -| TDE | `.devtrail/06-evolution/technical-debt/` | -| SEC | `.devtrail/08-security/` | -| MCARD | `.devtrail/09-ai-models/` | -| SBOM | `.devtrail/07-ai-audit/` | -| DPIA | `.devtrail/07-ai-audit/ethical-reviews/` | - -### Tags y Related - -Al poblar los campos `tags` y `related` en el frontmatter: - -**Tags:** -- Usar palabras clave en kebab-case: `sqlite`, `api-design`, `gnome-integration` -- 3 a 8 tags por documento describiendo tema, tecnología o componente -- Los tags habilitan búsqueda y categorización en `devtrail explore` - -**Related:** -- Referenciar únicamente otros **documentos DevTrail** — usar el nombre de archivo con extensión `.md` -- Si el documento está en un subdirectorio dentro de `.devtrail/`, incluir la ruta relativa: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-archivo.md` -- Si el documento está en el mismo directorio, el nombre de archivo es suficiente -- **No** colocar IDs de tareas (T001, US3), números de issues ni URLs externas en `related` — esos van en el cuerpo del documento - ---- - -## 6. Comunicación con Humanos - -### Ser Transparente - -- Explicar el razonamiento detrás de las decisiones -- Documentar alternativas consideradas -- Admitir incertidumbre cuando existe - -### Ser Conciso - -- Ir al grano -- Evitar jerga innecesaria -- Usar listas y tablas cuando sea apropiado - -### Ser Proactivo - -- Identificar riesgos potenciales -- Sugerir mejoras cuando sean evidentes -- Alertar sobre deuda técnica - ---- - -## 7. Manejo de Errores - -Si el agente comete un error: - -1. **Documentar** el error en un AILOG -2. **Explicar** qué salió mal -3. **Proponer** corrección -4. **Marcar** `review_required: true` - ---- - -## 8. Actualización de Documentos - -### Crear Nuevo vs Actualizar - -| Situación | Acción | -|-----------|--------| -| Corrección menor | Actualizar documento existente | -| Cambio significativo | Crear nuevo documento | -| Documento obsoleto | Marcar como `deprecated` | -| Reemplazo completo | Crear nuevo + marcar anterior como `superseded` | - -### Al Actualizar - -- Actualizar el campo `updated` en frontmatter -- Agregar nota en la sección de historial si existe -- Mantener consistencia con documentos relacionados - ---- - -## 9. Observabilidad (OpenTelemetry) - -Cuando se trabaja en proyectos que usan OpenTelemetry: - -### Reglas - -- **No** capturar PII, tokens o secretos en atributos o logs de OTel -- **Registrar** cambios en el pipeline de instrumentación (nuevos spans, atributos modificados, configuración del Collector) en AILOG con tag `observabilidad` -- **Crear** AIDEC o ADR al adoptar OTel en proyectos distribuidos — documentar la decisión de adopción y selección de backend -- **Establecer** `observability_scope` en el frontmatter cuando el cambio involucra instrumentación OTel - -### Disparadores de Documentación - -| Cambio | Documento | Adicional | -|--------|----------|-----------| -| Nuevos spans o atributos modificados | AILOG | Tag `observabilidad` | -| Selección de backend OTel | AIDEC o ADR | Si sistema distribuido | -| Configuración del pipeline del Collector | AILOG | Tag `observabilidad` | -| Cambios en estrategia de muestreo | AIDEC | Documentar justificación | -| Requisitos de observabilidad | REQ | Usar sección de Requisitos de Observabilidad | -| Pruebas de propagación de trazas | TES | Usar sección de Pruebas de Observabilidad | -| Incidente con evidencia de trazas | INC | Incluir trace_id/span_id en la línea temporal | -| Deuda de instrumentación | TDE | Tag `observabilidad` | - ---- - -## 10. Diagramas de Arquitectura (Modelo C4) - -Al crear documentos ADR que involucren cambios arquitectónicos: - -- **Incluir** un diagrama C4 con Mermaid al nivel apropiado -- **Usar** `C4Context` para decisiones a nivel de sistema (quién usa el sistema, dependencias externas) -- **Usar** `C4Container` para decisiones a nivel de servicio/contenedor (aplicaciones, bases de datos, colas de mensajes) -- **Usar** `C4Component` para decisiones de módulos internos (componentes dentro de un servicio) -- **Ver** `00-governance/C4-DIAGRAM-GUIDE.md` para referencia de sintaxis y ejemplos - -> Los diagramas son opcionales para decisiones menores. Usarlos cuando la decisión cambie fronteras del sistema, introduzca nuevos servicios o modifique comunicación entre servicios. - ---- - -## 11. Seguimiento de Especificaciones de API - -Cuando un cambio modifica endpoints de API: - -- **Verificar** que la especificación OpenAPI o AsyncAPI correspondiente esté actualizada -- **Referenciar** la ruta del spec en el AILOG o ADR usando el campo `api_spec_path` (en REQ) o `api_changes` (en ADR) -- **Documentar** cambios de API que rompen compatibilidad en un ADR con `risk_level: high` - ---- - -*DevTrail v4.1.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.devtrail/config.yml b/.devtrail/config.yml deleted file mode 100644 index af38560..0000000 --- a/.devtrail/config.yml +++ /dev/null @@ -1,12 +0,0 @@ -# DevTrail Configuration -# https://github.com/StrangeDaysTech/devtrail - -# Language setting for templates and documentation -# Supported values: en, es -# Default: en (English) -language: en - -# Complexity analysis settings (used by: devtrail analyze) -# Uncomment to override the default cognitive complexity threshold -# complexity: -# threshold: 8 diff --git a/.gemini/skills/devtrail-status/SKILL.md b/.gemini/skills/devtrail-status/SKILL.md deleted file mode 100644 index 68299f2..0000000 --- a/.gemini/skills/devtrail-status/SKILL.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -name: devtrail-status -description: Show DevTrail documentation status. Use to verify if AI agents properly documented their changes. ---- - -# DevTrail Status Skill - -This skill checks the documentation status of the DevTrail in the current project. - -## Instructions - -When invoked, perform the following checks and display the results: - -### 1. Find Recent DevTrail Documents - -Search for DevTrail documents created or modified in the last hour: - -```bash -# Get documents modified in the last hour -git log --since="1 hour ago" --name-only --pretty=format: -- ".devtrail/**/*.md" | sort -u | grep -v "^$" -``` - -If git is not available or the directory is not a git repo, use file modification times. -Check these directories for each document type: - -| Type | Prefix | Directory | -|------|--------|-----------| -| AILOG | `AILOG-` | `.devtrail/07-ai-audit/agent-logs/` | -| AIDEC | `AIDEC-` | `.devtrail/07-ai-audit/decisions/` | -| ADR | `ADR-` | `.devtrail/04-architecture/decisions/` | -| ETH | `ETH-` | `.devtrail/07-ai-audit/ethical-reviews/` | -| REQ | `REQ-` | `.devtrail/03-requirements/` | -| TES | `TES-` | `.devtrail/05-testing/` | -| INC | `INC-` | `.devtrail/06-operations/incidents/` | -| TDE | `TDE-` | `.devtrail/06-operations/tech-debt/` | -| SEC | `SEC-` | `.devtrail/08-security/` | -| MCARD | `MCARD-` | `.devtrail/09-ai-models/` | -| SBOM | `SBOM-` | `.devtrail/07-ai-audit/` | -| DPIA | `DPIA-` | `.devtrail/07-ai-audit/ethical-reviews/` | - -### 2. Find Modified Source Files - -Identify source files that were modified and might need documentation: - -```bash -# Get modified files (staged and unstaged) -git diff --name-only HEAD~1..HEAD 2>/dev/null || git diff --name-only -``` - -Filter to show only files that might need documentation: -- Exclude: `*.md`, `*.json`, `*.yml`, `*.yaml`, `*.lock`, `package-lock.json` -- Include: `*.ts`, `*.js`, `*.tsx`, `*.jsx`, `*.py`, `*.go`, `*.rs`, `*.java`, `*.cs`, `*.rb`, `*.php` - -### 3. Analyze Documentation Gaps - -For each modified source file, check if there's a corresponding DevTrail document: -- Files with >10 lines of changes in business logic folders should have an AILOG -- Security-related files (auth, crypto, secrets) should have a SEC assessment -- Architecture/structural changes should have an ADR -- AI/ML model changes should have a MCARD -- Dependency changes (`package.json`, `Cargo.toml`, `go.mod`, etc.) should have an SBOM -- Changes involving personal data processing should have a DPIA -- Test files should have a TES record -- Bug fixes or incidents should have an INC record - -### 4. Display Results - -Format the output as follows: - -``` -DevTrail Status -================================================================================ - -Recent Documents (last hour): - ✅ AILOG-2025-01-27-001-implement-auth.md - ✅ AIDEC-2025-01-27-001-auth-strategy.md - -Modified Files Without Documentation: - ⚠️ src/auth/login.ts (47 lines changed) - ⚠️ src/api/users.ts (23 lines changed) - -Summary: - Documents created: 2 - Files needing review: 2 - -Use /devtrail-new to create documentation for undocumented changes. -``` - -### Symbol Legend - -- ✅ = Documentation exists -- ⚠️ = May need documentation -- ℹ️ = Informational - -### Edge Cases - -1. **No git repository**: Show message explaining git is required for full functionality -2. **No recent documents**: Show "No DevTrail documents created in the last hour" -3. **No modified files**: Show "No source files modified recently" -4. **Empty .devtrail directory**: Show warning that DevTrail may not be properly set up - -### Additional Notes - -- This skill is read-only and does not create or modify files -- Run this after completing development tasks to verify documentation compliance -- If files need documentation, remind the user of the DevTrail rules diff --git a/.gemini/skills/devtrail-adr/SKILL.md b/.gemini/skills/straymark-adr/SKILL.md similarity index 85% rename from .gemini/skills/devtrail-adr/SKILL.md rename to .gemini/skills/straymark-adr/SKILL.md index 144f205..c911a4d 100644 --- a/.gemini/skills/devtrail-adr/SKILL.md +++ b/.gemini/skills/straymark-adr/SKILL.md @@ -1,9 +1,9 @@ --- -name: devtrail-adr +name: straymark-adr description: Create an ADR (Architecture Decision Record) for significant architectural decisions. Requires human review. --- -# DevTrail ADR Skill +# StrayMark ADR Skill Create an Architecture Decision Record (ADR) for significant architectural decisions. @@ -23,7 +23,7 @@ date +%Y-%m-%d git diff --stat HEAD~1 2>/dev/null || git diff --stat # Check for related ADRs -ls .devtrail/02-design/decisions/ADR-*.md 2>/dev/null | tail -5 +ls .straymark/02-design/decisions/ADR-*.md 2>/dev/null | tail -5 ``` ### 2. Confirm with User @@ -32,7 +32,7 @@ ls .devtrail/02-design/decisions/ADR-*.md 2>/dev/null | tail -5 ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail ADR ║ +║ StrayMark ADR ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ ⚠️ ADRs require human review after creation. ║ @@ -55,14 +55,14 @@ ls .devtrail/02-design/decisions/ADR-*.md 2>/dev/null | tail -5 ```bash # Count existing ADRs for today -ls .devtrail/02-design/decisions/ADR-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/02-design/decisions/ADR-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ### 4. Check Language and Load Template -Read `.devtrail/config.yml` for language setting: -- `en` (default): `.devtrail/templates/TEMPLATE-ADR.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-ADR.md` +Read `.straymark/config.yml` for language setting: +- `en` (default): `.straymark/templates/TEMPLATE-ADR.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-ADR.md` ### 5. Create Document @@ -87,18 +87,18 @@ Fill template with: - Implementation Plan: High-level steps - Success Metrics: How to validate the decision -Save to: `.devtrail/02-design/decisions/ADR-YYYY-MM-DD-NNN-description.md` +Save to: `.straymark/02-design/decisions/ADR-YYYY-MM-DD-NNN-description.md` ### 6. Report Result ``` ⚠️ ADR created (requires human review): - .devtrail/02-design/decisions/ADR-YYYY-MM-DD-NNN-description.md + .straymark/02-design/decisions/ADR-YYYY-MM-DD-NNN-description.md Status: draft Review Required: YES -DevTrail: Created ADR-YYYY-MM-DD-NNN-description.md (review required) +StrayMark: Created ADR-YYYY-MM-DD-NNN-description.md (review required) ``` ## Examples of Architectural Decisions diff --git a/.gemini/skills/devtrail-aidec/SKILL.md b/.gemini/skills/straymark-aidec/SKILL.md similarity index 82% rename from .gemini/skills/devtrail-aidec/SKILL.md rename to .gemini/skills/straymark-aidec/SKILL.md index 29ffdc3..1773e13 100644 --- a/.gemini/skills/devtrail-aidec/SKILL.md +++ b/.gemini/skills/straymark-aidec/SKILL.md @@ -1,9 +1,9 @@ --- -name: devtrail-aidec +name: straymark-aidec description: Create an AIDEC (AI Decision) document to record a technical decision with alternatives considered. --- -# DevTrail AIDEC Skill +# StrayMark AIDEC Skill Create an AI Decision (AIDEC) document to record technical decisions and the alternatives considered. @@ -27,7 +27,7 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail AIDEC ║ +║ StrayMark AIDEC ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ 📋 AIDEC documents a decision between alternatives. ║ @@ -44,14 +44,14 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat ```bash # Count existing AIDECs for today -ls .devtrail/07-ai-audit/decisions/AIDEC-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/07-ai-audit/decisions/AIDEC-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ### 4. Check Language and Load Template -Read `.devtrail/config.yml` for language setting: -- `en` (default): `.devtrail/templates/TEMPLATE-AIDEC.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-AIDEC.md` +Read `.straymark/config.yml` for language setting: +- `en` (default): `.straymark/templates/TEMPLATE-AIDEC.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-AIDEC.md` ### 5. Create Document @@ -70,15 +70,15 @@ Fill template with: - Decision: Which was chosen and justification - Consequences: Positive, negative, and risks -Save to: `.devtrail/07-ai-audit/decisions/AIDEC-YYYY-MM-DD-NNN-description.md` +Save to: `.straymark/07-ai-audit/decisions/AIDEC-YYYY-MM-DD-NNN-description.md` ### 6. Report Result ``` ✅ AIDEC created: - .devtrail/07-ai-audit/decisions/AIDEC-YYYY-MM-DD-NNN-description.md + .straymark/07-ai-audit/decisions/AIDEC-YYYY-MM-DD-NNN-description.md -DevTrail: Created AIDEC-YYYY-MM-DD-NNN-description.md +StrayMark: Created AIDEC-YYYY-MM-DD-NNN-description.md ``` ## When to Create an AIDEC diff --git a/.gemini/skills/devtrail-ailog/SKILL.md b/.gemini/skills/straymark-ailog/SKILL.md similarity index 81% rename from .gemini/skills/devtrail-ailog/SKILL.md rename to .gemini/skills/straymark-ailog/SKILL.md index 91ecf51..ad9fa7b 100644 --- a/.gemini/skills/devtrail-ailog/SKILL.md +++ b/.gemini/skills/straymark-ailog/SKILL.md @@ -1,9 +1,9 @@ --- -name: devtrail-ailog +name: straymark-ailog description: Create an AILOG (AI Action Log) document for the current changes. Quick shortcut for the most common document type. --- -# DevTrail AILOG Skill +# StrayMark AILOG Skill Quickly create an AI Action Log (AILOG) document for the current changes. @@ -30,7 +30,7 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail AILOG ║ +║ StrayMark AILOG ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ 📊 Changes detected: ║ @@ -48,16 +48,16 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat ```bash # Count existing AILOGs for today -ls .devtrail/07-ai-audit/agent-logs/AILOG-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/07-ai-audit/agent-logs/AILOG-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` Next number = count + 1, formatted as 3 digits (001, 002, etc.) ### 4. Check Language and Load Template -Read `.devtrail/config.yml` for language setting: -- `en` (default): `.devtrail/templates/TEMPLATE-AILOG.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-AILOG.md` +Read `.straymark/config.yml` for language setting: +- `en` (default): `.straymark/templates/TEMPLATE-AILOG.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-AILOG.md` ### 5. Create Document @@ -69,15 +69,15 @@ Fill template with: - `confidence`: based on change complexity - `risk_level`: based on files modified -Save to: `.devtrail/07-ai-audit/agent-logs/AILOG-YYYY-MM-DD-NNN-description.md` +Save to: `.straymark/07-ai-audit/agent-logs/AILOG-YYYY-MM-DD-NNN-description.md` ### 6. Report Result ``` ✅ AILOG created: - .devtrail/07-ai-audit/agent-logs/AILOG-YYYY-MM-DD-NNN-description.md + .straymark/07-ai-audit/agent-logs/AILOG-YYYY-MM-DD-NNN-description.md -DevTrail: Created AILOG-YYYY-MM-DD-NNN-description.md +StrayMark: Created AILOG-YYYY-MM-DD-NNN-description.md ``` ## Risk Level Guidelines diff --git a/.gemini/skills/straymark-audit-execute/SKILL.md b/.gemini/skills/straymark-audit-execute/SKILL.md new file mode 100644 index 0000000..e135d0b --- /dev/null +++ b/.gemini/skills/straymark-audit-execute/SKILL.md @@ -0,0 +1,151 @@ +--- +name: straymark-audit-execute +description: Execute an external audit of a Charter inside an auditor-side CLI (gemini-cli, claude-cli, copilot-cli, codex-cli). Reads the resolved audit prompt from the canonical location, audits with tool use, writes the report. Operator invokes one instance per CLI. +--- + +# StrayMark Audit Execute Skill + +Execute an external audit of a Charter inside this CLI session. Read the resolved audit prompt that StrayMark prepared at the canonical location, audit the implementation with tool use (citing `path:line` of files actually opened), and write the report at the canonical location for the audit-review skill to consolidate later. + +## When to invoke + +This skill runs **inside an auditor-side CLI** (gemini-cli, claude-cli, copilot-cli, codex-cli, or any agent runtime configured with read-only access to the adopter's repo). The operator opens the CLI in the repo, then invokes `/straymark-audit-execute `. + +The skill is the second step of the v1 audit cycle: + +1. In the main IDE: operator runs `/straymark-audit-prompt CHARTER-NN` → StrayMark writes `.straymark/audits/CHARTER-NN/audit-prompt.md`. +2. **(this skill)** Operator opens an auditor-side CLI in the repo and runs `/straymark-audit-execute CHARTER-NN`. Repeat in N CLIs (recommended: ≥2 of different model families). +3. When ALL audits commissioned have completed, operator returns to the main IDE and runs `/straymark-audit-review CHARTER-NN`. + +## Instructions + +### 1. Resolve the Charter + +The argument is optional. Two cases: + +**Case A — argument provided** (`/straymark-audit-execute CHARTER-04`): +Use the literal value. Construct the audit dir path: `.straymark/audits/CHARTER-04/`. + +**Case B — argument omitted** (`/straymark-audit-execute`): +Auto-discover pending prompts. Detect this auditor's model identifier (see step 2 for how) and produce its slug. Then: + +```bash +# List all audit prompts that exist +ls .straymark/audits/*/audit-prompt.md 2>/dev/null +``` + +For each found `.straymark/audits//audit-prompt.md`, check whether a report from this model already exists at `.straymark/audits//report-.md`. The set of "pending" prompts is the ones WITHOUT a corresponding report. + +- **Exactly one pending** → proceed with that CHARTER-ID, announcing the choice to the operator. +- **Multiple pending** → list them numerically with their Charter titles (read the title from the resolved prompt's `# Auditoría de Charter — CHARTER-NN` heading) and ask the operator to pick one. +- **None pending** → message: "No pending audit prompts for this model under `.straymark/audits/`. Either the operator has not run `/straymark-audit-prompt` in the main agent yet, or all the prompts already have a report from this model. Verify with the operator." + +### 2. Detect this auditor's model identifier + +Identify the model running this CLI session and produce a filesystem-safe slug. + +The operator will know the canonical model id of the auditor running this skill (for example `claude-sonnet-4-6`, `claude-opus-4-7`, `gemini-2.5-pro`, `gpt-5.3-codex`, `copilot-v1.0.40`). Slug rules: + +- Lowercase ASCII. +- Replace any character that isn't `[a-z0-9-]` with `-`. +- Collapse consecutive dashes to one. +- Trim leading/trailing dashes. + +Examples: + +| Model identifier | Slug | +|---|---| +| `claude-sonnet-4-6` | `claude-sonnet-4-6` | +| `gemini-2.5-pro` | `gemini-2-5-pro` | +| `gpt-5.3-codex` | `gpt-5-3-codex` | +| `copilot-v1.0.40` | `copilot-v1-0-40` | + +If the runtime does not expose the model identifier directly, ask the operator to confirm before proceeding. Do NOT fabricate a slug — collisions or wrong identifiers corrupt the review step. + +### 3. Read the audit prompt + +```bash +cat .straymark/audits//audit-prompt.md +``` + +The prompt is self-contained: it includes the Charter content, originating AILOGs, git diff, and the discipline rules (REGLA ABSOLUTA — SOLO LECTURA, evidence-citation discipline, severity calibration). Read it carefully before auditing. + +### 4. Audit with tool use + +Follow the prompt literally, with these expectations: + +- **Read-only**: never write to project files. The only output you are allowed to produce is the report at the canonical path in step 5. +- **Tool-use evidence**: every finding you record must cite `path:line` of files you actually opened via `Read`, `Grep`, or equivalent. Do not infer behavior from file names alone. +- **Severity calibration**: open the active configuration (factories, env defaults, build tags, deployment scaling) before declaring Critical/High severity. The Etapa 12 example in the prompt is a real case of inflation that the calibration discipline catches. +- **Scope discipline**: only report findings inside the Charter's declared scope. Out-of-scope observations go in their own section, not as defects. + +Track how many `path:line` citations you accumulate — it goes in the report frontmatter as `evidence_citations`. + +### 5. Write the report + +Output path: + +``` +.straymark/audits//report-.md +``` + +If a report at that exact path already exists (re-run on the same Charter with the same model), warn the operator before overwriting. The default is to overwrite — re-runs replace stale reports rather than coexist with them. + +If, by some unusual reason, two distinct sessions of the SAME model audited the same Charter and the operator wants both, append a numeric suffix manually: `report--2.md`. + +The report frontmatter MUST conform to `audit-output.schema.v0.json`: + +```yaml +--- +audit_role: auditor +auditor: # e.g., claude-sonnet-4-6 +charter_id: +git_range: "" +prompt_used: audit-prompt.md +audited_at: +findings_total: +findings_by_category: + hallucination: + implementation_gap: + real_debt: + false_positive: +evidence_citations: # how many path:line citations the body contains +audit_quality: high | medium | low +--- + +# (body following the format declared in the prompt's "Formato de salida" section) +``` + +### 6. Notify the operator — with the wait warning + +After writing the report, print this message verbatim (substituting ``, ``, and the finding count): + +``` +Audit complete for (this auditor: ). + + Report: .straymark/audits//report-.md + Findings: total () + +IMPORTANT: do NOT return to the main agent for /straymark-audit-review yet +unless ALL audits you commissioned have completed. + +If you opened other auditor CLIs (gemini-cli, copilot-cli, codex-cli, ...) +and have not yet seen their /straymark-audit-execute finish, wait for them. +Invoking /straymark-audit-review with incomplete reports produces a partial +consolidated analysis that you will have to discard or re-run — costing +you the audit cycle. + +When and only when ALL audits you commissioned are complete, return to +your main IDE and run: + + /straymark-audit-review +``` + +This wait warning matters: an operator with three CLIs open in parallel can be tempted to invoke review as soon as the first audit finishes. The review skill iterates whatever reports are present at the time it runs; it cannot wait for additional reports to arrive. + +## Notes + +- **No HTTP API calls.** This skill runs inside an auditor CLI that the operator chose; that CLI handles all model invocation, API keys, and rate limits. StrayMark orchestrates prompt resolution and report shape — nothing else. +- **Re-runs**: if you invoke this skill on a Charter whose report from this model already exists, the existing one is overwritten. The previous report is lost — if you wanted to keep it, copy it manually before re-running. +- **Multiple Charters in the same CLI session**: invoke the skill once per Charter. Reports do not collide because the filename is keyed on Charter id + model slug. +- **Heterogeneity inter-family**: the skill does not enforce that the operator uses different model families across the N audit-execute invocations. The recommendation is in the audit prompt itself and in `AGENT-RULES.md` §12; trust the operator. diff --git a/.gemini/skills/straymark-audit-prompt/SKILL.md b/.gemini/skills/straymark-audit-prompt/SKILL.md new file mode 100644 index 0000000..a60edfb --- /dev/null +++ b/.gemini/skills/straymark-audit-prompt/SKILL.md @@ -0,0 +1,84 @@ +--- +name: straymark-audit-prompt +description: Generate the unified audit prompt for a Charter at the canonical filesystem location. The operator then opens N auditor-side CLIs (gemini-cli, claude-cli, copilot-cli, etc.) and invokes /straymark-audit-execute in each — no copy/paste. Counterpart of /straymark-audit-review. +--- + +# StrayMark Audit Prompt Skill + +Generate the unified audit prompt for a Charter and write it to the canonical filesystem location. The operator then opens auditor-side CLIs in the same repo and invokes `/straymark-audit-execute` — the audit prompt is read directly from disk by each auditor; the operator never copies/pastes. + +## When to invoke + +Use this skill when the developer agreed to run an external audit at the Charter checkpoint (see `.straymark/00-governance/AGENT-RULES.md` § Audit checkpoint). + +The Charter should be in `in-progress` or `declared` status — auditing closed Charters is allowed but atypical (warn the operator and proceed only on confirmation). + +## Instructions + +### 1. Resolve the Charter + +Argument: a Charter identifier (`CHARTER-04`, `04`, or full id with slug). + +```bash +straymark charter status +``` + +Verify the Charter exists and capture its `status`. If `status: closed`, surface a one-line warning to the operator and ask whether to proceed. + +### 2. Generate the unified audit prompt + +```bash +straymark charter audit --prepare +``` + +The CLI writes the resolved prompt to: + +``` +.straymark/audits//audit-prompt.md +``` + +The prompt is self-contained: it embeds the Charter content, the originating AILOGs, the git diff over the resolved range (default `origin/main..HEAD`, falls back to `HEAD~1..HEAD` if no upstream is reachable), and the discipline rules (REGLA ABSOLUTA — SOLO LECTURA, evidence-citation, severity calibration). The prompt template lifts the seven universal sections from Sentinel's pre-StrayMark audit skill and parameterizes the project-specific hardcodes. + +The CLI does NOT invoke any LLM. It only resolves placeholders. + +### 3. Notify the operator + +After the CLI succeeds, print this guidance verbatim (substituting ``): + +``` +Audit prompt prepared for . + + Location: .straymark/audits//audit-prompt.md + (informational — you don't need to copy this path anywhere) + +Next steps: + + 1. Open one or more auditor-side CLIs (gemini-cli, claude-cli, + copilot-cli, codex-cli — whatever you have) in this repo. Each + CLI session uses its own model; recommendation is at least 2 + auditors of DIFFERENT model families, so cross-family blind + spots become signal when their findings converge. + + 2. In each auditor CLI, invoke: + + /straymark-audit-execute + + The skill is already installed (straymark init copies it to all + three platform locations). It reads the prompt from disk + automatically — you do not need to copy/paste anything. + + 3. When and only when ALL audits you commissioned have completed, + return to this main agent and run: + + /straymark-audit-review + + Reviewing with incomplete reports gives you a partial consolidated + analysis that you will have to discard or re-run. +``` + +## Notes + +- This skill is **orchestration-only**. It does NOT invoke LLM APIs, decide which models the operator uses, or wait for responses. It runs the CLI's `--prepare`, points the operator at the next-step skill, and exits. +- Re-running the skill on the same Charter regenerates the prompt at the same path. It does NOT touch operator-saved reports under `.straymark/audits//report-*.md`. +- Heterogeneity inter-family is recommended but not enforced in v0; the operator decides the model pairing across the N CLIs they open. +- For the rationale on cross-family auditors, see `dist/.straymark/audit-prompts/audit-prompt.md` § Tu rol or `Propuesta/straymark-cli-roadmap.md` §5.2 in the upstream repo. diff --git a/.gemini/skills/straymark-audit-review/SKILL.md b/.gemini/skills/straymark-audit-review/SKILL.md new file mode 100644 index 0000000..48e1081 --- /dev/null +++ b/.gemini/skills/straymark-audit-review/SKILL.md @@ -0,0 +1,252 @@ +--- +name: straymark-audit-review +description: Consolidate N external auditor reports into a critical review document with verdicts, remediation plan, and auditor ratings. Then merge the external_audit YAML block into the Charter telemetry. Counterpart of /straymark-audit-prompt and /straymark-audit-execute. +--- + +# StrayMark Audit Review Skill + +Critically evaluate the N external auditor reports for a Charter, cross-reference each finding against the actual source code, and produce a consolidated `review.md` with verdicts, a prioritized remediation plan, and per-auditor ratings. Then merge the `external_audit` YAML block into the Charter telemetry. + +This is the third and final step of the v1 audit cycle, and it is where the substance lives — the calibrator role (definitional reconciliation across heterogeneous auditor verdicts) is now performed by the main agent inline, replacing the v0 paste-based calibrator-reconciler prompt. + +## When to invoke + +After the operator has commissioned the audits in N auditor-side CLIs (each running `/straymark-audit-execute `) and **all of them have completed**. The operator returns to the main IDE and invokes: + +``` +/straymark-audit-review +``` + +If only some audits have completed, **do not proceed** — invoking the skill with incomplete reports produces a partial consolidated analysis. Verify with the operator that all the CLIs they opened have finished writing their reports under `.straymark/audits//report-*.md`. + +## Instructions + +### 1. Resolve the Charter and verify report set + +Argument: a Charter identifier. + +```bash +ls -la .straymark/audits// +``` + +Confirm: + +- `audit-prompt.md` exists (the prepared prompt the auditors read). +- `report-*.md` files exist (one per auditor that completed). At least 2 reports are recommended for cross-family heterogeneity to deliver signal; warn (do not block) if only 1 report is present. +- Match each `report-.md` filename against the model identifier in its frontmatter (`auditor:` field) to confirm consistency. Discrepancies are surfaced to the operator. + +If only the prompt is present and no reports exist, instruct the operator to run `/straymark-audit-execute` in the auditor CLIs first. + +### 2. Read all auditor reports + extract finding master list + +For each `.straymark/audits//report-*.md`: + +- Validate the frontmatter against `audit-output.schema.v0.json` (the CLI does this in step 6, but a soft check here gives an earlier and more readable error if any report is malformed). +- Extract: model identifier, total findings, findings by category, evidence_citations count, audit_quality. +- Parse the body for finding entries (typically `## Findings` → `### F1 — title — category` blocks with `Where:`, `What I observed:`, `Why I'm flagging it:`). + +Build a **master finding list** — every unique claim across all auditors, deduplicated when two auditors clearly describe the same thing. + +### 3. Verify every finding against actual code + +This is the substantive step. For EACH finding in the master list: + +**Launch Explore agents in parallel** (up to 3 at a time) to verify findings. Group findings by the file they reference and send related findings to the same agent. + +For each finding, the verification answers four questions: + +1. **Does the code actually have this problem?** Read the cited `path:line`. Is the claim accurate? +2. **Is it in scope?** Does the finding affect a task or file declared in the Charter? If it's outside the Charter's scope, classify as `MISATTRIBUTED`. +3. **What's the real severity given the CURRENT configuration?** Check active driver, feature flags, build tags, DB role, deployment scope (the calibration discipline from the audit prompt). The Etapa 12 example in the prompt is a real case of inflation that careful calibration catches. +4. **Is it a duplicate?** Does another auditor report the same finding differently? + +#### Verdict classification + +Each finding gets one of these verdicts: + +- **VALID** — Real problem, in scope, correctly described, correctly severized. +- **PARTIALLY VALID** — Real observation but wrong severity, missing nuance, or triggers only under a config not active in main. Include the reclassification. +- **MISATTRIBUTED** — Real observation but belongs to a different Charter or scope unit. +- **FALSE POSITIVE** — Claim is factually incorrect (file exists, code works as expected, the assumed driver isn't active, etc.). +- **DUPLICATE** — Same finding reported by another auditor (reference the original). + +#### Severity reclassification + +When the auditor's severity does not match the active configuration: + +- **Inflation** (auditor says Critical/High, code confirms only conditional): downgrade to Medium with explicit note on what config would activate it, OR move to "post-Charter / no bloqueante" if the trigger is a component not yet implemented. +- **Deflation** (auditor says Low/None, code shows a real trigger in current config): upgrade with evidence from the code path that activates it. +- **Correct inflation** (auditor says Critical and config confirms it): keep. + +An auditor that consistently inflates or deflates loses points in the auditor rating (step 5). + +### 4. Identify findings the auditors missed + +Based on your code exploration, check whether there are problems the auditors did NOT find. Focus on: + +- Security: SQL queries missing ownership filters, missing transaction boundaries, secrets in logs. +- Logic: input parameters ignored, dead code paths, unreachable branches. +- Consistency: naming mismatches between layers (model vs handler vs API). + +Mark these as "Missed by all auditors" in the remediation plan. + +### 5. Build the consolidated review.md + +Write the consolidated analysis to `.straymark/audits//review.md` with this structure (six sections, lifted from Sentinel's pre-StrayMark audit-review skill): + +```markdown +--- +audit_role: calibrator-reconciler +calibrator: +charter_id: +git_range: "" +prompt_used: ../audit-prompt.md +calibrated_at: +auditors_reconciled: + - report-.md + - report-.md + - ... +findings_consolidated: +findings_by_status: + agreed: + disputed: + unique_: + unique_: + rejected: +--- + +# Consolidated audit review — + +**Reviewer:** +**Date:** +**Confidence:** [High | Medium] + +## 1. Executive summary + +[2-3 paragraphs. Total findings count, scope confusion if any, most critical bug, +overall verdict on the Charter's implementation.] + +## 2. Scope definition + +[Table of Charter tasks, the closing criterion, and what IS vs IS NOT in scope +of this Charter. The auditors' findings are evaluated against THIS scope.] + +## 3. Per-auditor evaluation + +### 3.1 (model: ) + +| # | Finding | Reported severity | Verdict | Justification | +|---|---------|-------------------|---------|---------------| + +**Summary:** [2-3 sentences on this auditor's overall performance.] + +### 3.2 ... (same shape) + +## 4. Remediation plan — VALID and PARTIALLY VALID findings + +### P0 — Security +- **Files:** `path:line` +- **Problem:** [description with code evidence] +- **Remediation:** [specific approach] +- **Complexity:** [Low / Medium / High] +- **Detected by:** [auditor slug(s), or "Missed by all auditors" if you found it] + +### P1 — Integrity +[Same shape] + +### P2 — Consistency +[Same shape] + +### P3 — Robustness +[Same shape] + +### P4 — Documentation +[Same shape] + +## 5. Discarded findings — misattributions and false positives + +| Finding | Type | Charter / area | Auditor | +|---------|------|----------------|---------| + +## 6. Auditor ratings + +Score each auditor 1-10 across four criteria with weights: + +| Auditor | Scope precision (25%) | Technical depth (25%) | Bug detection (30%) | False positive rate (20%) | **Overall** | +|---------|:-:|:-:|:-:|:-:|:-:| +| | /10 | /10 | /10 | /10 | **/10** | +| ... + +### Justifications + +** — /10**: [2-3 sentences on what this auditor did well and where they slipped.] + +## 7. Conclusion + +[State of the Charter — clean / partial / deviated. Critical findings count. +Key remediation items the operator should address before close. +Recommended next step.] +``` + +### 6. Validate + emit external_audit YAML + +Run the CLI's merge step to validate all reports against the schema and emit the YAML block (combined with `--merge-into` if the operator's Charter telemetry already exists): + +**Branch A — telemetry exists** (operator already ran `straymark charter close` for this Charter, perhaps without audit, and is now adding audit findings retroactively): + +```bash +straymark charter audit --merge-reports \ + --merge-into .straymark/charters/.telemetry.yaml +``` + +The CLI appends the `external_audit:` array to the telemetry YAML. The CLI v1 deliberately rejects re-audit (file already has `external_audit:`) — if that fires, surface the message to the operator. Manual append is the fallback. + +**Branch B — telemetry does NOT exist** (the typical case: operator audits BEFORE closing): + +```bash +straymark charter audit --merge-reports +``` + +The YAML block prints to stdout. Capture it and write it to `.straymark/audits//external-audit-pending.yaml` so the operator can paste it into the telemetry when running `straymark charter close `. Tell the operator: "When you run `straymark charter close `, paste the `external_audit:` block from `.straymark/audits//external-audit-pending.yaml` when prompted." + +### 7. Notify the operator with a summary + +``` +Consolidated audit review complete for . + + Auditors reconciled: + Findings reported: + Findings VALID: (%) + False positives: + Misattributions: + Missed by all (you): + + Remediation plan: + P0 (Security): + P1 (Integrity): + P2-P4 (Other): + + Auditor ratings: + : /10 + : /10 + ... + + Documents written: + .straymark/audits//review.md + [either: .straymark/charters/.telemetry.yaml (merged)] + [or: .straymark/audits//external-audit-pending.yaml] + +Run `git diff` to review the changes before commit. +``` + +## Notes + +- **The calibrator role is in-conversation, not in a paste-based prompt.** v0 had a `calibrator-reconciler.md` template that the operator pasted into a separate model. v1 eliminates that round-trip — the main agent (this conversation) has filesystem access and can verify findings against code, which is what makes the consolidated review substantive instead of mechanical. +- **Heterogeneity inter-family is for the auditor pair, not the calibrator.** The calibrator (this skill, running in the main agent) may be of any family — even the same family as one of the auditors — because its task is definitional (apply the schema to already-produced verdicts), not discovery. +- **The review.md is the human-readable delivery; the YAML block is the machine-readable input to telemetry.** Both coexist by design. The operator reads `review.md`; `straymark metrics` and the Phase 2 telemetry aggregation read the YAML. +- **Re-running the skill** overwrites `review.md`. If the operator wants to keep the previous review (e.g., after a re-audit cycle), instruct them to copy it manually before re-running. +- **No HTTP API calls.** The skill runs the CLI's `--merge-reports` (which validates schemas and emits YAML), invokes Explore agents internally for code verification (which run in the main agent's context, not external APIs), and writes markdown. StrayMark does not invoke LLM APIs at any point. + +## Credit + +The six-section structure of `review.md` and the verdict vocabulary (VALID / PARTIALLY VALID / MISATTRIBUTED / FALSE POSITIVE / DUPLICATE) are lifted from the `audit-review/SKILL.md` skill mature pre-StrayMark in Sentinel, contributed via [issue #102](https://github.com/StrangeDaysTech/straymark/issues/102) by José Villaseñor Montfort (StrangeDaysTech). The four-criterion weighted auditor rating (Scope precision 25% / Technical depth 25% / Bug detection 30% / False positive rate 20%) is the same. Project-specific hardcodes parameterized. diff --git a/.gemini/skills/straymark-charter-new/SKILL.md b/.gemini/skills/straymark-charter-new/SKILL.md new file mode 100644 index 0000000..0ec508a --- /dev/null +++ b/.gemini/skills/straymark-charter-new/SKILL.md @@ -0,0 +1,111 @@ +--- +name: straymark-charter-new +description: Scaffold a Charter — StrayMark's bounded unit of work that pairs declarative ex-ante scope with telemetry ex-post. Use when starting a multi-session implementation block (>1 day, >5 tasks, multi-phase). +--- + +# StrayMark Charter Scaffold Skill + +Declare a Charter at the start of a bounded, auditable unit of work — *not* every change. Charters wrap multi-session work that warrants a stable scope contract you can drift-check at close. They are conceptually distinct from the 12+4 governance document types (AILOG, ADR, AIDEC, …): Charters live at `.straymark/charters/NN-slug.md` and use a sequential prefix instead of a date prefix. + +> See `STRAYMARK.md §15` and `.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md` for the lifecycle and the SpecKit ↔ Charter bridge. + +## When to use this skill + +Trigger on any of: + +- Multi-session implementation block (>1 day, >5 tasks across phases). +- Work that warrants external audit at completion. +- A SpecKit feature has reached `tasks.md` and the operator wants a stable scope contract before `/speckit-implement`. +- The user asks to "declare", "open", or "start" a Charter. + +If the work is a single-session change → use `/straymark-ailog` instead. + +## Instructions + +### 1. Gather context + +```bash +# Sequential number of the Charter being created +straymark charter list 2>/dev/null | tail -5 || true + +# Surrounding spec / AILOG context — Charters frequently originate from one +ls specs/*/spec.md 2>/dev/null | head -5 +ls .straymark/07-ai-audit/agent-logs/AILOG-*.md 2>/dev/null | tail -5 +``` + +### 2. Confirm with user + +``` +╔══════════════════════════════════════════════════════════════════╗ +║ StrayMark Charter — declare a bounded unit of work ║ +╠══════════════════════════════════════════════════════════════════╣ +║ ║ +║ 📋 A Charter pairs declarative scope (ex-ante) with telemetry ║ +║ (ex-post). Lifecycle: declared → in-progress → closed. ║ +║ ║ +║ Required: ║ +║ 1. Title (one line) ║ +║ 2. Effort estimate: XS | S | M | L ║ +║ ║ +║ One of (optional but encouraged): ║ +║ 3a. --from-ailog AILOG-ID (post-MVP / maintenance origin) ║ +║ 3b. --from-spec specs/.../spec.md (greenfield / SpecKit origin) ║ +║ ║ +║ Default effort: M. ║ +║ ║ +╚══════════════════════════════════════════════════════════════════╝ +``` + +### 3. Pick origin and effort + +- **Effort heuristic**: XS (≤ half day), S (≤ 1 day), M (1–3 days, default), L (≥ 1 week). +- **Origin precedence**: a single live AILOG → `--from-ailog`; a SpecKit feature spec → `--from-spec`; otherwise omit (the operator can fill `originating_*` fields manually). + +### 4. Run the CLI + +The CLI does the scaffolding — slug derivation, sequential numbering, template substitution, write to `.straymark/charters/NN-slug.md`. The skill's job is to drive it with the right flags. + +```bash +# Greenfield, SpecKit-driven +straymark charter new \ + --title "Workspace foundation for peek MVP" \ + --type M \ + --from-spec specs/001-peek-mvp-foundation/spec.md + +# Post-MVP / maintenance, AILOG-driven +straymark charter new \ + --title "Per-service anomaly thresholds" \ + --type S \ + --from-ailog AILOG-2026-04-28-021 + +# No explicit origin (operator fills frontmatter manually) +straymark charter new --title "Refactor signal pipeline" --type M +``` + +If the title would derive a poor slug, pass `--slug ` explicitly. + +### 5. Hand off to the operator + +After the file is created, the CLI's "Next steps" output already lists what to fill. Surface it verbatim, then add: + +> **Reminder**: Charter status starts at `declared`. Flip to `in-progress` only when execution actually begins. Run `straymark charter drift CHARTER-NN` before `straymark charter close` to catch declared-but-not-modified files (or modified-but-not-declared ones). + +### 6. Report result + +``` +✓ Charter declared: + .straymark/charters/NN-slug.md + + charter_id: CHARTER-NN-slug + status: declared + effort_estimate: + origin: + +StrayMark: Created CHARTER-NN-slug +``` + +## What this skill does NOT do + +- **It does not flip status to `in-progress` or `closed`.** Lifecycle transitions are operator decisions. +- **It does not run drift or audit.** Use `straymark charter drift` and `/straymark-audit-prompt` / `/straymark-audit-execute` / `/straymark-audit-review` for those phases. +- **It does not replace AILOGs.** Day-to-day work inside the Charter still produces AILOGs; the Charter aggregates them via `originating_ailogs:`. diff --git a/.gemini/skills/devtrail-mcard/SKILL.md b/.gemini/skills/straymark-mcard/SKILL.md similarity index 94% rename from .gemini/skills/devtrail-mcard/SKILL.md rename to .gemini/skills/straymark-mcard/SKILL.md index 5fba11b..cf49de1 100644 --- a/.gemini/skills/devtrail-mcard/SKILL.md +++ b/.gemini/skills/straymark-mcard/SKILL.md @@ -1,9 +1,9 @@ --- -name: devtrail-mcard +name: straymark-mcard description: Create a Model/System Card (MCARD) document through an interactive step-by-step flow. Guides the user through each section with specific questions and example responses. --- -# DevTrail MCARD Skill +# StrayMark MCARD Skill Create AI Model/System Card documentation through an interactive guided flow. @@ -13,7 +13,7 @@ When invoked, follow these steps: ### 1. Check for Parameters -If the user specified a model name (e.g., `/devtrail-mcard GPT-4o`), use it as the model name and proceed to step 2 asking only for the model type. +If the user specified a model name (e.g., `/straymark-mcard GPT-4o`), use it as the model name and proceed to step 2 asking only for the model type. If no parameter is given, proceed to step 2 asking for both model name and type. @@ -23,7 +23,7 @@ Ask the user: ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail MCARD — Model/System Card ║ +║ StrayMark MCARD — Model/System Card ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ Step 1/7: Model Identity ║ @@ -230,15 +230,15 @@ Based on the gathered information, determine: ### 10. Check Language Configuration -Read `.devtrail/config.yml` to determine language: +Read `.straymark/config.yml` to determine language: ```yaml language: en # or es ``` Use template path based on language: -- `en` (default): `.devtrail/templates/TEMPLATE-MCARD.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-MCARD.md` +- `en` (default): `.straymark/templates/TEMPLATE-MCARD.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-MCARD.md` ### 11. Generate Document ID @@ -249,7 +249,7 @@ Determine the next sequence number: date +%Y-%m-%d # Find existing MCARD documents for today -ls .devtrail/09-ai-models/MCARD-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/09-ai-models/MCARD-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ID format: `MCARD-YYYY-MM-DD-NNN` @@ -260,7 +260,7 @@ Display a summary and ask for confirmation: ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail MCARD — Summary ║ +║ StrayMark MCARD — Summary ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ Model: [model_name] ([model_type]) ║ @@ -273,7 +273,7 @@ Display a summary and ask for confirmation: ║ MCARD-YYYY-MM-DD-NNN-[model-name-slug].md ║ ║ ║ ║ Location: ║ -║ .devtrail/09-ai-models/ ║ +║ .straymark/09-ai-models/ ║ ║ ║ ║ Review required: YES ║ ║ ║ @@ -294,15 +294,15 @@ Wait for user confirmation before proceeding. - `[Model Name]` -> User-provided model name 3. Fill in all sections with the gathered information 4. Set `review_required: true` in the frontmatter -5. Save to `.devtrail/09-ai-models/MCARD-YYYY-MM-DD-NNN-[model-name-slug].md` +5. Save to `.straymark/09-ai-models/MCARD-YYYY-MM-DD-NNN-[model-name-slug].md` ### 14. Report Result After creation, display: ``` -DevTrail MCARD created: - .devtrail/09-ai-models/MCARD-YYYY-MM-DD-NNN-[description].md +StrayMark MCARD created: + .straymark/09-ai-models/MCARD-YYYY-MM-DD-NNN-[description].md Model: [model_name] ([model_type]) Provider: [provider] @@ -313,8 +313,8 @@ DevTrail MCARD created: ## Edge Cases -1. **No `.devtrail/09-ai-models/` directory**: Create it before saving +1. **No `.straymark/09-ai-models/` directory**: Create it before saving 2. **User provides partial information**: Fill known fields, mark unknown fields with `[To be determined]` 3. **User declines confirmation**: Acknowledge and exit gracefully 4. **Third-party model with limited info**: Mark unknown sections with `[Information not publicly available]` and note in limitations -5. **No `.devtrail/config.yml`**: Default to English (`en`) +5. **No `.straymark/config.yml`**: Default to English (`en`) diff --git a/.gemini/skills/devtrail-new/SKILL.md b/.gemini/skills/straymark-new/SKILL.md similarity index 69% rename from .gemini/skills/devtrail-new/SKILL.md rename to .gemini/skills/straymark-new/SKILL.md index 8af349a..6b77dc2 100644 --- a/.gemini/skills/devtrail-new/SKILL.md +++ b/.gemini/skills/straymark-new/SKILL.md @@ -1,11 +1,11 @@ --- -name: devtrail-new -description: Create DevTrail documentation. Analyzes context to suggest document type or accepts explicit type parameter. Always confirms before creating. +name: straymark-new +description: Create StrayMark documentation. Analyzes context to suggest document type or accepts explicit type parameter. Always confirms before creating. --- -# DevTrail New Skill +# StrayMark New Skill -Create DevTrail documentation based on recent changes. +Create StrayMark documentation based on recent changes. ## Instructions @@ -13,10 +13,12 @@ When invoked, follow these steps: ### 1. Check for Parameters -If the user specified a document type (e.g., `/devtrail-new ailog`), skip to step 4 using that type. +If the user specified a document type (e.g., `/straymark-new ailog`), skip to step 4 using that type. Valid types: `ailog`, `aidec`, `adr`, `eth`, `req`, `tes`, `inc`, `tde`, `sec`, `mcard`, `sbom`, `dpia` +> **Charter is not a `straymark new` type.** Charters are bounded units of work (filename `NN-slug.md`, sequential prefix) and have their own command. If the user asks for a Charter (`/straymark-new charter`, *"create a Charter"*, *"declare a Charter"*), redirect to `/straymark-charter-new`. + ### 2. Analyze Context Gather information about recent changes: @@ -35,7 +37,7 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat git diff --numstat HEAD~1 2>/dev/null || git diff --numstat # Check code complexity (primary method for AILOG trigger) -devtrail analyze --output json 2>/dev/null +straymark analyze --output json 2>/dev/null # If CLI unavailable, fall back to line count heuristic in step 3 ``` @@ -45,14 +47,16 @@ Based on the analysis, suggest a document type: | Pattern | Suggested Type | |---------|---------------| -| Complex code (`devtrail analyze` `above_threshold > 0`; fallback: >20 lines) | AILOG | +| Complex code (`straymark analyze` `above_threshold > 0`; fallback: >20 lines) | AILOG | | Multiple implementation alternatives discussed | AIDEC | | Structural/architectural changes, new modules | ADR | | Files with `auth`, `user`, `privacy`, `gdpr` | ETH (draft) | | Test files (`*.test.*`, `*.spec.*`) | TES | | Bug fixes, hotfixes | INC | -| `TODO`, `FIXME`, `HACK` comments added | TDE | +| `TODO`, `FIXME`, `HACK` comments added | TDE (code-smell trigger) | +| Transversal debt — heritage from prior Charter, applies to multiple modules, requires dedicated Charter, or needs human prioritization | TDE (architectural trigger — distinct from per-Charter `R`; see AGENT-RULES.md §3) | | Requirements or spec files | REQ | +| Multi-session implementation block (>1 day, >5 tasks, multi-phase) | **Charter** — redirect to `/straymark-charter-new` (Charters use `straymark charter new`, not `straymark new`) | ### 4. Confirm with User @@ -60,7 +64,7 @@ Based on the analysis, suggest a document type: ``` ╔══════════════════════════════════════════════════════════════════╗ -║ DevTrail New ║ +║ StrayMark New ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ 📊 Analysis: ║ @@ -83,15 +87,15 @@ Wait for user confirmation before proceeding. ### 5. Check Language Configuration -Read `.devtrail/config.yml` to determine language: +Read `.straymark/config.yml` to determine language: ```yaml language: en # or es ``` Use template path based on language: -- `en` (default): `.devtrail/templates/TEMPLATE-[TYPE].md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-[TYPE].md` +- `en` (default): `.straymark/templates/TEMPLATE-[TYPE].md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-[TYPE].md` ### 6. Generate Document ID @@ -99,7 +103,7 @@ Determine the next sequence number: ```bash # Find existing documents of this type for today -ls .devtrail/*/[TYPE]-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/*/[TYPE]-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ID format: `[TYPE]-YYYY-MM-DD-NNN` @@ -116,18 +120,18 @@ ID format: `[TYPE]-YYYY-MM-DD-NNN` | Type | Location | |------|----------| -| AILOG | `.devtrail/07-ai-audit/agent-logs/` | -| AIDEC | `.devtrail/07-ai-audit/decisions/` | -| ETH | `.devtrail/07-ai-audit/ethical-reviews/` | -| ADR | `.devtrail/02-design/decisions/` | -| REQ | `.devtrail/01-requirements/` | -| TES | `.devtrail/04-testing/` | -| INC | `.devtrail/05-operations/incidents/` | -| TDE | `.devtrail/06-evolution/technical-debt/` | -| SEC | `.devtrail/08-security/` | -| MCARD | `.devtrail/09-ai-models/` | -| SBOM | `.devtrail/07-ai-audit/` | -| DPIA | `.devtrail/07-ai-audit/ethical-reviews/` | +| AILOG | `.straymark/07-ai-audit/agent-logs/` | +| AIDEC | `.straymark/07-ai-audit/decisions/` | +| ETH | `.straymark/07-ai-audit/ethical-reviews/` | +| ADR | `.straymark/02-design/decisions/` | +| REQ | `.straymark/01-requirements/` | +| TES | `.straymark/04-testing/` | +| INC | `.straymark/05-operations/incidents/` | +| TDE | `.straymark/06-evolution/technical-debt/` | +| SEC | `.straymark/08-security/` | +| MCARD | `.straymark/09-ai-models/` | +| SBOM | `.straymark/07-ai-audit/` | +| DPIA | `.straymark/07-ai-audit/ethical-reviews/` | ### 7.5. Apply Automatic Review Rules @@ -144,8 +148,8 @@ These rules align with the CLI validation rules CROSS-001, CROSS-002, and CROSS- After creation, display: ``` -✅ DevTrail document created: - .devtrail/[path]/[TYPE]-YYYY-MM-DD-NNN-description.md +✅ StrayMark document created: + .straymark/[path]/[TYPE]-YYYY-MM-DD-NNN-description.md Review required: [yes/no] Risk level: [low/medium/high/critical] diff --git a/.gemini/skills/devtrail-sec/SKILL.md b/.gemini/skills/straymark-sec/SKILL.md similarity index 88% rename from .gemini/skills/devtrail-sec/SKILL.md rename to .gemini/skills/straymark-sec/SKILL.md index 64dc89c..f3f9cf7 100644 --- a/.gemini/skills/devtrail-sec/SKILL.md +++ b/.gemini/skills/straymark-sec/SKILL.md @@ -1,15 +1,15 @@ --- -name: devtrail-sec -description: Create a DevTrail Security Assessment (SEC) document. Interactive step-by-step flow that gathers scope, threat model methodology, and OWASP ASVS level, then generates a pre-filled SEC document based on code context. Always marks as draft with review_required. +name: straymark-sec +description: Create a StrayMark Security Assessment (SEC) document. Interactive step-by-step flow that gathers scope, threat model methodology, and OWASP ASVS level, then generates a pre-filled SEC document based on code context. Always marks as draft with review_required. --- -# DevTrail Security Assessment Skill +# StrayMark Security Assessment Skill Create a Security Assessment document with threat modeling and OWASP ASVS compliance checks. ## Instructions -When invoked via `/devtrail-sec [component-name]`, follow these steps: +When invoked via `/straymark-sec [component-name]`, follow these steps: ### 1. Gather Assessment Scope @@ -89,7 +89,7 @@ Also scan the codebase for security-relevant patterns in the component area: ``` +------------------------------------------------------------------+ -| DevTrail Security Assessment | +| StrayMark Security Assessment | +------------------------------------------------------------------+ | | | Component: [component-name] | @@ -112,15 +112,15 @@ Wait for user confirmation before proceeding. ### 6. Check Language Configuration -Read `.devtrail/config.yml` to determine language: +Read `.straymark/config.yml` to determine language: ```yaml language: en # or es ``` Use template path based on language: -- `en` (default): `.devtrail/templates/TEMPLATE-SEC.md` -- `es`: `.devtrail/templates/i18n/es/TEMPLATE-SEC.md` +- `en` (default): `.straymark/templates/TEMPLATE-SEC.md` +- `es`: `.straymark/templates/i18n/es/TEMPLATE-SEC.md` ### 7. Generate Document ID @@ -128,7 +128,7 @@ Determine the next sequence number: ```bash # Find existing SEC documents for today -ls .devtrail/08-security/SEC-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l +ls .straymark/08-security/SEC-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l ``` ID format: `SEC-YYYY-MM-DD-NNN` @@ -153,15 +153,15 @@ ID format: `SEC-YYYY-MM-DD-NNN` - `review_required: true` - `risk_level: high` - `confidence: medium` -5. Save to: `.devtrail/08-security/SEC-YYYY-MM-DD-NNN-[description].md` +5. Save to: `.straymark/08-security/SEC-YYYY-MM-DD-NNN-[description].md` ### 9. Report Result After creation, display: ``` -DevTrail Security Assessment created: - .devtrail/08-security/SEC-YYYY-MM-DD-NNN-description.md +StrayMark Security Assessment created: + .straymark/08-security/SEC-YYYY-MM-DD-NNN-description.md Status: draft Review required: yes @@ -175,7 +175,7 @@ DevTrail Security Assessment created: ## Expected Output Example -For invocation `/devtrail-sec authentication-api`, after the interactive flow selects STRIDE and L1, the generated document would look like: +For invocation `/straymark-sec authentication-api`, after the interactive flow selects STRIDE and L1, the generated document would look like: ```markdown --- @@ -284,7 +284,7 @@ related: [] | Decision | [APPROVED / REJECTED / CONDITIONAL] | | Conditions | [If applicable] | - + ``` ## Edge Cases diff --git a/.gemini/skills/straymark-status/SKILL.md b/.gemini/skills/straymark-status/SKILL.md new file mode 100644 index 0000000..7152cc7 --- /dev/null +++ b/.gemini/skills/straymark-status/SKILL.md @@ -0,0 +1,124 @@ +--- +name: straymark-status +description: Show StrayMark documentation status. Use to verify if AI agents properly documented their changes. +--- + +# StrayMark Status Skill + +This skill checks the documentation status of the StrayMark in the current project. + +## Instructions + +When invoked, perform the following checks and display the results: + +### 1. Find Recent StrayMark Documents + +Search for StrayMark documents created or modified in the last hour: + +```bash +# Get documents modified in the last hour +git log --since="1 hour ago" --name-only --pretty=format: -- ".straymark/**/*.md" | sort -u | grep -v "^$" +``` + +If git is not available or the directory is not a git repo, use file modification times. +Check these directories for each document type: + +| Type | Prefix | Directory | +|------|--------|-----------| +| AILOG | `AILOG-` | `.straymark/07-ai-audit/agent-logs/` | +| AIDEC | `AIDEC-` | `.straymark/07-ai-audit/decisions/` | +| ADR | `ADR-` | `.straymark/02-design/decisions/` | +| ETH | `ETH-` | `.straymark/07-ai-audit/ethical-reviews/` | +| REQ | `REQ-` | `.straymark/01-requirements/` | +| TES | `TES-` | `.straymark/04-testing/` | +| INC | `INC-` | `.straymark/05-operations/incidents/` | +| TDE | `TDE-` | `.straymark/06-evolution/technical-debt/` | +| SEC | `SEC-` | `.straymark/08-security/` | +| MCARD | `MCARD-` | `.straymark/09-ai-models/` | +| SBOM | `SBOM-` | `.straymark/07-ai-audit/` | +| DPIA | `DPIA-` | `.straymark/07-ai-audit/ethical-reviews/` | + +Also enumerate **Charters** (bounded units of work — distinct from doc types; see STRAYMARK.md §15): + +```bash +# Charters list with status counts (declared / in-progress / closed) +straymark charter list 2>/dev/null +``` + +If the project has no Charters yet but the work clearly fits the trigger (multi-session implementation block, >5 tasks across phases, audit value), surface that as a gap and recommend `/straymark-charter-new`. + +### 2. Find Modified Source Files + +Identify source files that were modified and might need documentation: + +```bash +# Get modified files (staged and unstaged) +git diff --name-only HEAD~1..HEAD 2>/dev/null || git diff --name-only +``` + +Filter to show only files that might need documentation: +- Exclude: `*.md`, `*.json`, `*.yml`, `*.yaml`, `*.lock`, `package-lock.json` +- Include: `*.ts`, `*.js`, `*.tsx`, `*.jsx`, `*.py`, `*.go`, `*.rs`, `*.java`, `*.cs`, `*.rb`, `*.php` + +Run complexity analysis on modified source files: + +```bash +# Analyze complexity of changed files (primary method for AILOG trigger) +straymark analyze --output json 2>/dev/null +# If CLI unavailable, fall back to line count heuristic in step 3 +``` + +### 3. Analyze Documentation Gaps + +For each modified source file, check if there's a corresponding StrayMark document: +- Complex code (`straymark analyze` reports `summary.above_threshold > 0`; **fallback** if CLI unavailable: >20 lines of business logic) should have an AILOG +- Security-related files (auth, crypto, secrets) should have a SEC assessment +- Architecture/structural changes should have an ADR +- AI/ML model changes should have a MCARD +- Dependency changes (`package.json`, `Cargo.toml`, `go.mod`, etc.) should have an SBOM +- Changes involving personal data processing should have a DPIA +- Test files should have a TES record +- Bug fixes or incidents should have an INC record +- Multi-session implementation blocks (>1 day, >5 tasks, multi-phase) should have an open or closed **Charter** at `.straymark/charters/` + +### 4. Display Results + +Format the output as follows: + +``` +StrayMark Status +================================================================================ + +Recent Documents (last hour): + ✅ AILOG-2025-01-27-001-implement-auth.md + ✅ AIDEC-2025-01-27-001-auth-strategy.md + +Modified Files Without Documentation: + ⚠️ src/auth/login.ts (cognitive: 12, threshold: 8) + ⚠️ src/api/users.ts (cognitive: 9, threshold: 8) + +Summary: + Documents created: 2 + Files needing review: 2 + +Use /straymark-new to create documentation for undocumented changes. +``` + +### Symbol Legend + +- ✅ = Documentation exists +- ⚠️ = May need documentation +- ℹ️ = Informational + +### Edge Cases + +1. **No git repository**: Show message explaining git is required for full functionality +2. **No recent documents**: Show "No StrayMark documents created in the last hour" +3. **No modified files**: Show "No source files modified recently" +4. **Empty .straymark directory**: Show warning that StrayMark may not be properly set up + +### Additional Notes + +- This skill is read-only and does not create or modify files +- Run this after completing development tasks to verify documentation compliance +- If files need documentation, remind the user of the StrayMark rules diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index bf88320..c1f2228 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,22 +1,23 @@ -# DevTrail - GitHub Copilot Configuration +# StrayMark - GitHub Copilot Configuration - -> **Read and follow the rules in [../DEVTRAIL.md](../DEVTRAIL.md).** -> That file contains all DevTrail documentation governance rules for this project. - + +> **Read and follow the rules in [../STRAYMARK.md](../STRAYMARK.md).** +> That file contains all StrayMark documentation governance rules for this project. + --- -## DevTrail Rules for Copilot +## StrayMark Rules for Copilot When assisting with code changes in this project, follow these documentation rules: **Document when:** -- Complex code change → suggest running `devtrail analyze`; if `above_threshold > 0`, suggest AILOG (fallback: >20 lines) +- Complex code change → suggest running `straymark analyze`; if `above_threshold > 0`, suggest AILOG (fallback: >20 lines) - Choosing between alternatives → suggest creating AIDEC - Changing auth/PII/security → suggest AILOG (risk_level: high) + ETH draft - Changing public API or DB schema → suggest AILOG + consider ADR - Changing ML models or prompts → suggest AILOG + human review +- Starting a multi-session implementation block (>1 day, >5 tasks, multi-phase) → suggest declaring a Charter (`straymark charter new`) **Always:** - Identify as `copilot-v{version}` in the `agent:` field @@ -33,4 +34,4 @@ When assisting with code changes in this project, follow these documentation rul --- -*DevTrail | [Strange Days Tech](https://strangedays.tech) — Because every change tells a story.* +*StrayMark | [Strange Days Tech](https://strangedays.tech) — Because every change tells a story.* diff --git a/.github/workflows/docs-validation.yml b/.github/workflows/docs-validation.yml index f34d759..2f7dcb3 100644 --- a/.github/workflows/docs-validation.yml +++ b/.github/workflows/docs-validation.yml @@ -1,5 +1,5 @@ # ============================================================================= -# DevTrail - Documentation Validation Workflow +# StrayMark - Documentation Validation Workflow # ============================================================================= # # This workflow validates documentation on each Pull Request and push to main. @@ -20,12 +20,21 @@ on: push: branches: [main, develop] paths: - - '.devtrail/**' + - '.straymark/**' - '.github/workflows/docs-validation.yml' pull_request: branches: [main, develop] paths: - - '.devtrail/**' + - '.straymark/**' + +# Single source of truth for the DocType prefixes the workflow recognizes. +# Adding a new DocType requires updating BOTH this list and +# `cli/src/document.rs::DocType::ALL_PREFIXES`. Keep them in sync. +# Files whose basename does not start with one of these prefixes followed by +# `-` are treated as framework / governance / template files and are silently +# skipped from the per-document checks (no manual exclude list needed). +env: + DOC_TYPE_PREFIXES: "AILOG|AIDEC|ADR|ETH|REQ|TES|INC|TDE|SEC|MCARD|SBOM|DPIA|PIPIA|CACFILE|TC260RA|AILABEL" jobs: validate-docs: @@ -60,7 +69,7 @@ jobs: uses: tj-actions/changed-files@v44 with: files: | - .devtrail/**/*.md + .straymark/**/*.md # ========================================================================= # Validate file naming convention @@ -71,23 +80,34 @@ jobs: echo "📋 Validating file naming convention..." ERRORS=0 - # Canonical source of valid types: cli/src/document.rs::DocType::ALL_PREFIXES - VALID_PATTERN="^(ADR|REQ|TES|OPS|INC|TDE|AILOG|AIDEC|ETH|DOC|SEC|MCARD|SBOM|DPIA)-[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{3}-[a-z0-9-]+\.md$" - EXCLUDED="PRINCIPLES.md|DOCUMENTATION-POLICY.md|AGENT-RULES.md|TEMPLATE-.*\.md|README.md|QUICK-REFERENCE.md|INDEX.md|GIT-BRANCHING-STRATEGY.md" + # Whitelist approach: only files whose basename starts with one of + # the known DocType prefixes are validated. Framework / governance / + # template files (e.g., AGENT-RULES.md, AI-KPIS.md, NIST-AI-RMF-*) + # don't match any prefix and are silently skipped — no manual + # exclude list to maintain. + PREFIX_RE="^(${DOC_TYPE_PREFIXES})-" + # Optional single-letter suffix on the sequence number lets adopters + # resolve same-day same-sequence filename collisions without + # renumbering downstream entries (e.g. `-028b-` when `-028-` is + # already taken by an earlier-committed file on the same date). + VALID_PATTERN="^(${DOC_TYPE_PREFIXES})-[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{3}[a-z]?-[a-z0-9-]+\.md$" for file in ${{ steps.changed-files.outputs.all_changed_files }}; do filename=$(basename "$file") - # Skip excluded files - if echo "$filename" | grep -qE "$EXCLUDED"; then - echo " ⊘ Excluded: $filename" + # Skip files that are not adopter-created typed documents. + if ! echo "$filename" | grep -qE "$PREFIX_RE"; then + echo " ⊘ Skipped (framework / non-typed): $filename" continue fi - # Validate naming convention + # File starts with a DocType prefix — validate the full pattern. if ! echo "$filename" | grep -qE "$VALID_PATTERN"; then echo " ✗ Invalid naming: $filename" - echo " Expected: [TYPE]-[YYYY-MM-DD]-[NNN]-[description].md" + echo " Expected: [TYPE]-[YYYY-MM-DD]-[NNN]-[description].md" + echo " Where is an optional single lowercase letter for same-day" + echo " same-sequence collisions (e.g. -028b- when -028- is taken)." + echo " Valid TYPEs: ${DOC_TYPE_PREFIXES//|/, }" ERRORS=$((ERRORS + 1)) else echo " ✓ $filename" @@ -110,14 +130,14 @@ jobs: echo "📋 Validating metadata..." ERRORS=0 - EXCLUDED="PRINCIPLES.md|DOCUMENTATION-POLICY.md|AGENT-RULES.md|TEMPLATE-.*\.md|README.md|QUICK-REFERENCE.md|INDEX.md|GIT-BRANCHING-STRATEGY.md" + PREFIX_RE="^(${DOC_TYPE_PREFIXES})-" REQUIRED_FIELDS="id title status created" for file in ${{ steps.changed-files.outputs.all_changed_files }}; do filename=$(basename "$file") - # Skip excluded files - if echo "$filename" | grep -qE "$EXCLUDED"; then + # Only validate adopter-created typed documents. + if ! echo "$filename" | grep -qE "$PREFIX_RE"; then continue fi @@ -153,13 +173,13 @@ jobs: echo "📋 Validating risk_level and review_required..." ERRORS=0 - EXCLUDED="PRINCIPLES.md|DOCUMENTATION-POLICY.md|AGENT-RULES.md|TEMPLATE-.*\.md|README.md|QUICK-REFERENCE.md|INDEX.md|GIT-BRANCHING-STRATEGY.md" + PREFIX_RE="^(${DOC_TYPE_PREFIXES})-" for file in ${{ steps.changed-files.outputs.all_changed_files }}; do filename=$(basename "$file") - # Skip excluded files - if echo "$filename" | grep -qE "$EXCLUDED"; then + # Only validate adopter-created typed documents. + if ! echo "$filename" | grep -qE "$PREFIX_RE"; then continue fi @@ -306,20 +326,23 @@ jobs: uses: tj-actions/changed-files@v44 with: files: | - .devtrail/**/*.md + .straymark/**/*.md - name: Verify high-risk documents have ETH reference if: steps.changed-files.outputs.any_changed == 'true' run: | echo "📋 Checking compliance: high-risk documents must reference an ETH..." - ERRORS=0 - EXCLUDED="PRINCIPLES.md|DOCUMENTATION-POLICY.md|AGENT-RULES.md|TEMPLATE-.*\.md|README.md|QUICK-REFERENCE.md|INDEX.md|GIT-BRANCHING-STRATEGY.md" + # NOTE: Missing-ETH is intentionally a warning (not an error) — adopters + # may file the ETH later in a follow-up document. No ERRORS counter is + # kept because there is no exit-1 path; the warnings ride through the + # normal CI run and surface in the GitHub Actions UI. + PREFIX_RE="^(${DOC_TYPE_PREFIXES})-" for file in ${{ steps.changed-files.outputs.all_changed_files }}; do filename=$(basename "$file") - if echo "$filename" | grep -qE "$EXCLUDED"; then + if ! echo "$filename" | grep -qE "$PREFIX_RE"; then continue fi @@ -347,12 +370,12 @@ jobs: run: | echo "📋 Checking EU AI Act compliance..." - EXCLUDED="PRINCIPLES.md|DOCUMENTATION-POLICY.md|AGENT-RULES.md|TEMPLATE-.*\.md|README.md|QUICK-REFERENCE.md|INDEX.md|GIT-BRANCHING-STRATEGY.md" + PREFIX_RE="^(${DOC_TYPE_PREFIXES})-" for file in ${{ steps.changed-files.outputs.all_changed_files }}; do filename=$(basename "$file") - if echo "$filename" | grep -qE "$EXCLUDED"; then + if ! echo "$filename" | grep -qE "$PREFIX_RE"; then continue fi @@ -390,54 +413,58 @@ jobs: run: | echo "📊 Generating governance metrics..." - DEVTRAIL_DIR=".devtrail" - TYPES=("AILOG" "AIDEC" "ADR" "ETH" "REQ" "TES" "INC" "TDE" "SEC" "MCARD" "SBOM" "DPIA") + STRAYMARK_DIR=".straymark" + # Derive the types array from the workflow-level env var so we never + # have to maintain it in two places. + IFS='|' read -ra TYPES <<< "$DOC_TYPE_PREFIXES" # Header - echo "## DevTrail Governance Metrics" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo "Generated: $(date -u +"%Y-%m-%d %H:%M UTC")" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - - # Document counts by type - echo "### Documents by Type" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo "| Type | Count |" >> "$GITHUB_STEP_SUMMARY" - echo "|------|------:|" >> "$GITHUB_STEP_SUMMARY" + { + echo "## StrayMark Governance Metrics" + echo "" + echo "Generated: $(date -u +"%Y-%m-%d %H:%M UTC")" + echo "" + echo "### Documents by Type" + echo "" + echo "| Type | Count |" + echo "|------|------:|" + } >> "$GITHUB_STEP_SUMMARY" TOTAL=0 for TYPE in "${TYPES[@]}"; do - COUNT=$(find "$DEVTRAIL_DIR" -name "${TYPE}-*.md" -not -path "*/templates/*" 2>/dev/null | wc -l) + COUNT=$(find "$STRAYMARK_DIR" -name "${TYPE}-*.md" -not -path "*/templates/*" 2>/dev/null | wc -l) TOTAL=$((TOTAL + COUNT)) echo "| $TYPE | $COUNT |" >> "$GITHUB_STEP_SUMMARY" done - echo "| **TOTAL** | **$TOTAL** |" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - # Documents from the last 7 days - echo "### Recent Documents (last 7 days)" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" WEEK_AGO=$(date -u -d "7 days ago" +%Y-%m-%d 2>/dev/null || date -u -v-7d +%Y-%m-%d 2>/dev/null || echo "0000-00-00") - RECENT=$(find "$DEVTRAIL_DIR" -name "*.md" -not -path "*/templates/*" -newer <(date -d "$WEEK_AGO" +%s 2>/dev/null || echo /dev/null) 2>/dev/null | wc -l || echo 0) - echo "Documents created/modified in the last 7 days: **$RECENT**" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" + RECENT=$(find "$STRAYMARK_DIR" -name "*.md" -not -path "*/templates/*" -newer <(date -d "$WEEK_AGO" +%s 2>/dev/null || echo /dev/null) 2>/dev/null | wc -l || echo 0) - # Risk level distribution - echo "### Risk Level Distribution" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo "| Risk Level | Count |" >> "$GITHUB_STEP_SUMMARY" - echo "|------------|------:|" >> "$GITHUB_STEP_SUMMARY" + { + echo "| **TOTAL** | **$TOTAL** |" + echo "" + echo "### Recent Documents (last 7 days)" + echo "" + echo "Documents created/modified in the last 7 days: **$RECENT**" + echo "" + echo "### Risk Level Distribution" + echo "" + echo "| Risk Level | Count |" + echo "|------------|------:|" + } >> "$GITHUB_STEP_SUMMARY" for RISK in low medium high critical; do - RISK_COUNT=$(grep -rl "^risk_level: *$RISK" "$DEVTRAIL_DIR" --include="*.md" 2>/dev/null | grep -v templates | wc -l) + RISK_COUNT=$(grep -rl "^risk_level: *$RISK" "$STRAYMARK_DIR" --include="*.md" 2>/dev/null | grep -vc templates || echo 0) echo "| $RISK | $RISK_COUNT |" >> "$GITHUB_STEP_SUMMARY" done - echo "" >> "$GITHUB_STEP_SUMMARY" - # Review compliance rate - echo "### Review Compliance" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - HIGH_RISK_DOCS=$(grep -rl "^risk_level: *\(high\|critical\)" "$DEVTRAIL_DIR" --include="*.md" 2>/dev/null | grep -v templates || true) + { + echo "" + echo "### Review Compliance" + echo "" + } >> "$GITHUB_STEP_SUMMARY" + + HIGH_RISK_DOCS=$(grep -rl "^risk_level: *\(high\|critical\)" "$STRAYMARK_DIR" --include="*.md" 2>/dev/null | grep -v templates || true) HIGH_COUNT=$(echo "$HIGH_RISK_DOCS" | grep -c . 2>/dev/null || echo 0) if [ "$HIGH_COUNT" -gt 0 ]; then REVIEWED=0 @@ -472,7 +499,7 @@ jobs: run: | echo "📚 Generating documentation index..." - cat > .devtrail/INDEX.md << 'EOF' + cat > .straymark/INDEX.md << 'EOF' # Documentation Index *Automatically generated on $(date -u +"%Y-%m-%d %H:%M UTC")* @@ -481,31 +508,33 @@ jobs: EOF # List documents by folder - for folder in .devtrail/*/; do + for folder in .straymark/*/; do folder_name=$(basename "$folder") - echo "" >> .devtrail/INDEX.md - echo "## ${folder_name}" >> .devtrail/INDEX.md - echo "" >> .devtrail/INDEX.md + { + echo "" + echo "## ${folder_name}" + echo "" + } >> .straymark/INDEX.md - find "$folder" -name "*.md" -type f | sort | while read file; do + find "$folder" -name "*.md" -type f | sort | while IFS= read -r file; do filename=$(basename "$file") # Extract title from front-matter or use filename title=$(grep "^title:" "$file" 2>/dev/null | sed 's/title: *//' | head -1 || echo "$filename") - echo "- [$title]($file)" >> .devtrail/INDEX.md + echo "- [$title]($file)" >> .straymark/INDEX.md done done - echo "✅ Index generated: .devtrail/INDEX.md" + echo "✅ Index generated: .straymark/INDEX.md" - name: Commit index if changed run: | git config --local user.email "github-actions[bot]@users.noreply.github.com" git config --local user.name "github-actions[bot]" - if git diff --quiet .devtrail/INDEX.md; then + if git diff --quiet .straymark/INDEX.md; then echo "No changes to index" else - git add .devtrail/INDEX.md + git add .straymark/INDEX.md git commit -m "docs: update documentation index [skip ci]" git push fi diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index e8235d5..17905cd 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -100,7 +100,7 @@ arborist-cli is deliberately scoped. These boundaries are constitutional: - **Not a linter** — reports metrics, does not enforce rules - **Not a CI gate** — use the library directly or check exit codes; the CLI does not manage pipelines -- **Not a replacement for DevTrail** — DevTrail uses complexity as *input* to +- **Not a replacement for StrayMark** — StrayMark uses complexity as *input* to documentation decisions; this CLI reports the raw metrics - **Thin wrapper only** — all analysis logic lives in `arborist-metrics`; the CLI adds argument parsing, directory traversal, and output formatting diff --git a/.specify/starter/IDEA.md b/.specify/starter/IDEA.md index bc9a68f..ff7ad63 100644 --- a/.specify/starter/IDEA.md +++ b/.specify/starter/IDEA.md @@ -12,7 +12,7 @@ of the `arborist-metrics` API. ## Why? -When we integrated `arborist-metrics` into DevTrail, we realized that the library's +When we integrated `arborist-metrics` into StrayMark (formerly DevTrail), we realized that the library's value isn't limited to Rust projects embedding it as a dependency. There are two underserved audiences: @@ -24,7 +24,7 @@ underserved audiences: triage, or exploratory analysis — without committing to a full CI pipeline integration. -The DevTrail CLI (`devtrail`) already has complexity awareness, but its scope is +The StrayMark CLI (`straymark`) already has complexity awareness, but its scope is documentation governance — it's overkill when you just want to ask "how complex is this file?" or "which functions in this directory exceed threshold X?". @@ -95,7 +95,7 @@ For CI/scripting integration: - Not a linter (doesn't enforce rules, just reports metrics) - Not a CI gate (use the library directly for that, or check exit codes) -- Not a replacement for DevTrail (DevTrail uses complexity as *input* to documentation +- Not a replacement for StrayMark (StrayMark uses complexity as *input* to documentation decisions; this CLI just reports the raw metrics) ## Relationship to arborist-metrics diff --git a/.straymark/.checksums.json b/.straymark/.checksums.json new file mode 100644 index 0000000..e341354 --- /dev/null +++ b/.straymark/.checksums.json @@ -0,0 +1,174 @@ +{ + "version": "4.17.0", + "files": { + ".straymark/templates/i18n/zh-CN/TEMPLATE-MCARD.md": "a44b6839f8e99b348070b11860fc72d5f7dc994d5fd0e604e5875d9653fdbabf", + ".straymark/00-governance/i18n/es/GB-45438-LABELING-GUIDE.md": "8e447687d00e3dfb9c07498e673b4f62207a749fb244d2f5e36551014bf8643e", + ".straymark/templates/i18n/zh-CN/TEMPLATE-TES.md": "8e0537b8c3fa9883c235d5e8a8ff9a825deea193be4ecd85e78cc7b28d4220e3", + ".straymark/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md": "75a0bc5935620df16ca4dc40da4d3c9383aad20c0582c3cfa7acf0aff55ee1ff", + ".straymark/00-governance/i18n/zh-CN/SPECKIT-CHARTER-BRIDGE.md": "86c8325c1edb5874ef4e4f4d60f93707a413217b46c1c87b48aa1b49c940ada7", + ".straymark/templates/i18n/es/TEMPLATE-SEC.md": "2371394f9f8863adfa571baae9abc2a33c451775a995c40f3e2cac256630b04f", + ".straymark/00-governance/i18n/es/ISO-25010-2023-REFERENCE.md": "d702e5ea546486beb935e2bc49d221d9bc9bdc2228906833ded15bf5b602d9c0", + ".straymark/07-ai-audit/decisions/AIDEC-2026-04-03-001-cli-restructure-and-self-update-strategy.md": "76c110a7afa10578598a84de3b4b285b63664ac3fe02a880ab8bb7e541e2aa0c", + ".straymark/00-governance/i18n/zh-CN/AI-LIFECYCLE-TRACKER.md": "342be350dd7a7bc7135b081b91064c1fabafcc0bff6b40d762b90d0add050fa3", + ".straymark/00-governance/i18n/es/MANAGEMENT-REVIEW-TEMPLATE.md": "dca187565a315d625f5950e8df05e713b185f74d2f419828be420de775da72cd", + ".straymark/00-governance/C4-DIAGRAM-GUIDE.md": "6bb231233c7957ad1d9b91d376f5a2cd027c5364d2d15a0287507e64a299af8d", + ".straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md": "fc940600a27ed9a4fc6437fb1613d7f2bff6aa49285a05351afc582e705e3eeb", + ".straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-005-fix-binary-name.md": "1f1dfd368edf6067d556e68251c6346b64492ed1a8938038ddcc0519660b3704", + ".straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-003-cargo-dist-release-infrastructure.md": "87cbb6f47766aec0019d7a5ec9856373f7c8e0b95a64fecaf3d60443363b33ad", + ".straymark/00-governance/i18n/es/AI-RISK-CATALOG.md": "03fd6b95a2917b6fb16f31e7622be34fd2d77ae23e35b47b67c6b86a0aa4be3b", + ".straymark/templates/i18n/es/TEMPLATE-AILABEL.md": "45896f5548fa688e3d7af47cf7fd70a0b3a21b1a72a652eb3720fabb6fc7c031", + ".straymark/00-governance/i18n/es/AI-LIFECYCLE-TRACKER.md": "6c45520beed409bf59dbf496ce30be3ff02dcb870290dd40649383799d74fee5", + ".straymark/00-governance/QUICK-REFERENCE.md": "da0a1f993778aee22f38090fa26eff3e5977cac07c33c79ee94b06c4e24638fc", + ".straymark/templates/TEMPLATE-SBOM.md": "63b12459a75baac37a6ca69008bded565e9d4876dcafc8636e8e9a05ac87193f", + ".straymark/templates/i18n/es/TEMPLATE-PIPIA.md": "7560a634a0484fcb16192146d617812cc1048204ffd761f749ebbaaa2326759a", + ".straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-001-add-integration-test-suite.md": "b06a06cb70da4f787781f018c81209b634aa952828c5a804117b2111f14da73f", + ".straymark/templates/charter/i18n/zh-CN/charter-template.md": "09505db7907843d9eb4b8e3e1172704d1084574cd5be5ee9d410ee96dc28aaaa", + ".straymark/00-governance/GIT-BRANCHING-STRATEGY.md": "ca165418e42a396c66edf801fa71fc5da3add903c8c2ee35da706928d2194728", + ".straymark/templates/TEMPLATE-CACFILE.md": "dabfc70f42a4b441cd6e5bbd92d9cff35f3e37aabb8e9eaa3c68dd57d3e47816", + ".straymark/00-governance/exceptions/.gitkeep": "b4aaf3d190e7dc76189a91d721842a6b74aa9aa9fcb5619ce0d1c5a16f60bf6d", + ".straymark/00-governance/i18n/es/PIPL-PIPIA-GUIDE.md": "1eaba2df6eff107f7126b7ef990110615eabf57dd139f87981c95040525c5909", + ".straymark/00-governance/i18n/zh-CN/AI-KPIS.md": "5be08376dcc7ec4406216762350b72dac7ed765ddbc334bd5c4504171db50ca5", + ".straymark/00-governance/i18n/zh-CN/AI-GOVERNANCE-POLICY.md": "e82bcd63f0146cb66d3beb35a39d3604a2ca43461eeb2873606096bbd684f00f", + ".straymark/03-implementation/i18n/es/NIST-AI-RMF-GOVERN-GUIDE.md": "88381cca102901e983194404d5445d4696b73dbaf641a6128b205af6b0286984", + ".straymark/03-implementation/i18n/zh-CN/NIST-AI-600-1-GENAI-RISKS.md": "f6fe254f84622ada39e2537c5ff088f54cf07ab2402a3779b7aa2371ba250ad0", + ".straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-GOVERN-GUIDE.md": "d9841a73a8fbd7add3a27ca90d6af96fa43ab10e33858d501a1e0a02e9436613", + ".straymark/templates/i18n/zh-CN/TEMPLATE-AIDEC.md": "3bd1649c19e6f56d085b003799609ee2594da47f91da9aa9ec62842e789daad8", + ".straymark/templates/charter/charter-telemetry-template.yaml": "1f22bfd50b1d581699818c09cd3d8ca6873c3dbea148af29a6d1522698c4a4b6", + ".straymark/templates/i18n/zh-CN/TEMPLATE-ADR.md": "0382b299ee60dea18cee148026f4cefb953738a7b5ee3a6f18f1f14c78d7031a", + ".straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-MEASURE-GUIDE.md": "2465b6bc4750b1c61d8fdd321dd1ad10c94fad8e65094e2e74f2c745b344157b", + ".straymark/templates/i18n/es/TEMPLATE-TDE.md": "322c2d861cfeb080ccc75a4728825502754282cc1c23e37ca4afdf4f0bd98503", + ".straymark/07-ai-audit/decisions/.gitkeep": "c7c86a6c44e638da00088beeca6797a11ecdd84dafbaae6210905cc86a13486f", + "STRAYMARK.md": "5292db4e6825523a33cd407bf3c0a1cd25738e4e285cd6fedc7959ad6b32e913", + ".straymark/00-governance/GB-45438-LABELING-GUIDE.md": "cf0b61ccb9672a5d7c0d681d972e32bb029cb029117205ce9831b11ec5adda67", + ".straymark/00-governance/i18n/zh-CN/TC260-IMPLEMENTATION-GUIDE.md": "fbcf0f709084fc2b0729b5c040d8e440f13a412c9594cba4bfe0c246e8e410bc", + ".straymark/00-governance/i18n/es/PRINCIPLES.md": "1127a0b2f9756110811aac0de1b5e18352f4124f180254053e28391184949467", + ".straymark/03-implementation/i18n/es/NIST-AI-RMF-MANAGE-GUIDE.md": "19251b01178286bc5c48baa70797d7b9f00954d8f838aedd05a1cf3c56eb0048", + ".straymark/00-governance/i18n/zh-CN/CAC-FILING-GUIDE.md": "64342c55cd989eda5572671f3b5002868427eec018babe4d191e8ce1e255f0c9", + ".straymark/templates/charter/i18n/es/charter-template.md": "d3ea32a9a36724230e4016c9618155497006551ce95ce9e03ebbb165997f7ec7", + ".straymark/templates/i18n/es/TEMPLATE-TC260RA.md": "04f1daad1f11b39586b2fc59e7c3738b67471cf445f7124e477ebab91e0185f7", + ".straymark/templates/TEMPLATE-MCARD.md": "f72567856ab5f78129a03695f6976dd8cfbb64ef6974b3a5c671123732f19ca3", + ".straymark/templates/TEMPLATE-AIDEC.md": "169119a5e9e386817cba67778c6f3201390bcb0c5120aab2e77aea44f3e39b10", + ".straymark/templates/TEMPLATE-ETH.md": "768e6e32d3f83158fa81816c646e05810042adbcd3d007907007a1cf777c0ca8", + ".straymark/00-governance/AI-KPIS.md": "ff87081ff4155ddc2fa8c706521d1d23ec4287a5254918f7c77be074d00d09e2", + ".straymark/03-implementation/i18n/es/NIST-AI-600-1-GENAI-RISKS.md": "302b05589fd548b637166ecbeaa4c63c2ac563b7cfa8b78c20123cd3b51504b7", + ".straymark/templates/TEMPLATE-REQ.md": "736eda155f48484c437a3754055ebf9d8705d9bbc00af43a6a9d5ec9216a31c4", + ".straymark/templates/i18n/zh-CN/TEMPLATE-AILOG.md": "8411505375160f85d107bb24ae5052e29dd2e6fbe12c3b929334e1653573fe87", + ".straymark/QUICK-REFERENCE.md": "7c01d200ab0ef7d77ed16a4a3d5a0d19981efb4a01d9e535bc10d3d8c3bae5d1", + ".straymark/09-ai-models/.gitkeep": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + ".straymark/config.yml": "147df29bc8217097bec143436d3fc51d74250de72789a944837efeecc263f088", + ".straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md": "6796b298174bb586c584be5a75a42ff6d267d993bb49d3cd6ab05d301fc1752a", + ".straymark/00-governance/i18n/es/DOCUMENTATION-POLICY.md": "7678193aeb0014057ea499be51037e9b403410cd5dd4b7cd01a5cebee53a1cc2", + ".straymark/00-governance/CAC-FILING-GUIDE.md": "e8eb5997947eda98a529673b1a33c67d5c7045bee691e2785a17487eaf5e1259", + ".straymark/templates/TEMPLATE-ADR.md": "8f5fda2aa1a029b2f0280f34d4cbb4e7240422fd18a91c41670a745bd2046011", + ".straymark/00-governance/i18n/es/CHARTER-CHAIN-EVOLUTION.md": "fe869818bde964b279106cfe61bfb6e1c2aa4644e3b5f287904e5b462bcd18f1", + ".straymark/00-governance/PIPL-PIPIA-GUIDE.md": "d5525118b2a96f199594b6970de1435167b8d376fbda06c01000d5d569c8e4f3", + ".straymark/templates/i18n/es/TEMPLATE-AIDEC.md": "bb8beb96d469feb7ee75b51c7e4fb224207d2732de372fcd3c6070d0a119b72c", + ".straymark/00-governance/i18n/zh-CN/OBSERVABILITY-GUIDE.md": "13754aef4f75e8325acc7cc00e94fc29177ae5b6ded163bab1796bdab25f3511", + ".straymark/00-governance/i18n/zh-CN/CHINA-REGULATORY-FRAMEWORK.md": "15d663444b13880b2fec9bec7242a461469fbc29a2e868469dc0c1342dd8d3d1", + ".straymark/00-governance/i18n/zh-CN/PIPL-PIPIA-GUIDE.md": "ea36b2fb28167a2991059430fdb5941f65df78a1857779c843dd399ea014de0b", + ".straymark/03-implementation/.gitkeep": "6f47b5c66f0e61dc78e4e57f7a4d858336bdc3866f3a26a397f3e2a1869810c0", + ".straymark/00-governance/i18n/es/CHINA-REGULATORY-FRAMEWORK.md": "7982f83ca64893b8b220f823178d8394ba1ede957927104eb83e7c0d8bd2728e", + ".straymark/00-governance/i18n/zh-CN/CHARTER-CHAIN-EVOLUTION.md": "166c588f84c7079bf0f752128dd41edd63385d984ff6450ce9e80484e8f3e78d", + ".straymark/schemas/charter.schema.v0.json": "8088aed6bdf2fd2c0baf080f3f3cbc72c97c9fad59e6767b476541f6bb97c625", + ".straymark/00-governance/i18n/zh-CN/QUICK-REFERENCE.md": "78e6def63c2f4b2157af9f513645f9a02eb75ff78e319c03c01c0929922b40d8", + ".straymark/templates/i18n/es/TEMPLATE-ETH.md": "499c3da42ad145370f5270b4e6dcb786774d8fed58eb8a2e3082ae90cf447e3b", + ".straymark/08-security/.gitkeep": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + ".straymark/06-evolution/technical-debt/.gitkeep": "a1e8aa0b06407e59dee1a6f3f52e47a6044aeca3fcc2a2108c853cb775428a6a", + ".straymark/templates/i18n/zh-CN/TEMPLATE-PIPIA.md": "6ab14be9646855e2f59d4ad23e6388309d48fe1f9db474ae541ed5d9ba3f99ed", + ".straymark/00-governance/i18n/es/TC260-IMPLEMENTATION-GUIDE.md": "ec6a617388a5ebbdc2d7821c4193ba876131e007c8713d75f483df8b36a971f6", + ".straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-MANAGE-GUIDE.md": "2a2d6c099ab1afa7da9afc612bfe601d1ae046155ccd93c89a95e28afa4ae674", + ".straymark/.checksums.json": "23228a7e6a1c07d55fc496593a3c1c6ef3aae4b271327ca258a7d023065b1c87", + ".straymark/audit-prompts/audit-prompt.md": "714ef62051f407ae609350b2ce06e6d153f62c61c0c21819ad92106083f61493", + ".straymark/templates/i18n/zh-CN/TEMPLATE-ETH.md": "dc53846625e4e10f6f6026bc51a3a10969fd664f5147fc3923b7e448da644cff", + ".straymark/00-governance/i18n/es/SPECKIT-CHARTER-BRIDGE.md": "eb25b2893d621e25d596ebd1fe0a6946350e50c21023ddf7b48ded34e2b29409", + ".straymark/00-governance/CHINA-REGULATORY-FRAMEWORK.md": "206be07ad39be89f30ab21e6ba63b54291935132cbd5acbc4ff376f2986a01fb", + ".straymark/03-implementation/NIST-AI-600-1-GENAI-RISKS.md": "39925646e8f493e4086b19c478cef32c703bb303192316c2f287837b21fb52fe", + ".straymark/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md": "1201f3356e5e821b23ea8c19d9a833e28c3313beda469a28ccf305f7f43f7f49", + ".straymark/03-implementation/NIST-AI-RMF-GOVERN-GUIDE.md": "32f32b1f90ad83ab117ecbc134b869301004af85f8426ec84164447780b30752", + ".straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-002-ci-workflow-and-crates-metadata.md": "c54fd99c8cf4e832ac15312156a7416ec3eec08cd9d5da7455df0ddae67cbdea", + ".straymark/00-governance/i18n/zh-CN/GB-45438-LABELING-GUIDE.md": "d1575f05c03cb32331df7fe6d4465532d3a0fdf75e46daa51b7f1502703e5b3d", + ".straymark/templates/i18n/zh-CN/TEMPLATE-CACFILE.md": "4375023df05f18c03539fa761cc94c2be503d893a29de5ca6f240b7a400674ad", + ".straymark/templates/i18n/zh-CN/TEMPLATE-SEC.md": "2e92dc4ccf07896b94f3666f975dfb744d430dcede01090ad4f533d33b368fb1", + ".straymark/00-governance/AGENT-RULES.md": "8d8e81b83abab361e7b14afa756132adaa335feaaedb19b5de1255835f87640d", + ".straymark/00-governance/AI-RISK-CATALOG.md": "586411737da2936d9728855bbeacf0baba163b7afccbbf091495e95ab341097e", + ".straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-MAP-GUIDE.md": "34a5e94e79afcf0ab5de2fdc6c6e732301f4eb08bfc67d9296e270c575117d0d", + ".straymark/05-operations/runbooks/.gitkeep": "165100a8abe03040590c2ee3b051950527bf0250f8c5febaf529a27089751bc3", + ".straymark/07-ai-audit/agent-logs/AILOG-2026-04-04-001-about-subcommand.md": "c342890ec900e83aaa9c22994a5460d03d1dfa7aed8bc6add9de1b6946dda360", + ".straymark/07-ai-audit/ethical-reviews/.gitkeep": "a300a8f3c231fbb98a5e04e3165ef8b3f4fe5af9cc7f77467c26244194ce0d45", + ".straymark/schemas/charter-telemetry.schema.v0.json": "fc5c784ddf4f36c3ece03a970fcd24b7789d0e3686e635a2cebbd6f606a6ece3", + ".straymark/templates/i18n/es/TEMPLATE-CACFILE.md": "f66f5e6036162ccb69dbbb04d88b580d0c6e1b0813e89bc9434c8a2975bc5aca", + ".straymark/07-ai-audit/agent-logs/.gitkeep": "9f44184239ba322e5771ca92e19e789d0dcd4d59475e2474fdb7bb5eff99048f", + ".straymark/templates/i18n/zh-CN/TEMPLATE-TDE.md": "3c76d7dceb9ab04269af2f2cfaf4e87d34569093ec8bf76232f5788db6285ac9", + ".straymark/00-governance/i18n/es/QUICK-REFERENCE.md": "d7393d90f0403a61a1755ba434f9edced1a89fcd719119b40f2233c89fd0bc6f", + ".straymark/templates/i18n/zh-CN/TEMPLATE-INC.md": "10d572b5ee347c79e5dc4d135fada22662f0b1a7e7fd245126f0cb89a2b4d2ca", + ".straymark/templates/i18n/es/TEMPLATE-TES.md": "5243b4cad67e626c0446aab7b16e9a04d837c14e37d60eab09f71b5ba59b059c", + ".straymark/00-governance/i18n/zh-CN/AI-RISK-CATALOG.md": "7c62918f40b04c4e15749199b845916fa46c80a1eb217a482b5409880d2d9fb0", + ".straymark/00-governance/i18n/es/CAC-FILING-GUIDE.md": "b65ab776feb241c7b9d3d876a437dab3e2b48bc5f11e67ac0f3dd95141816deb", + ".straymark/00-governance/AI-GOVERNANCE-POLICY.md": "9d3218cbc810ac82e173b47ec01d260e8e0944080fb9d34bc6e655988d3c52bf", + ".straymark/07-ai-audit/agent-logs/AILOG-2026-04-02-002-implement-core-cli-mvp.md": "d8aa79631df96544fbec9201b8ce2fab08cf9ec9795f6b69de95167c6243f28a", + ".straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-004-update-subcommand.md": "29f1d2771d094931a807839e5d9285e3ea074b75470816542c9e5e099f598711", + ".straymark/04-testing/.gitkeep": "1d8198124b57687ba4120fc888f855ffa707c93113d54d3c46c77f5152bd430f", + ".straymark/00-governance/i18n/es/EMERGENT-OBSERVATION-DESIGN.md": "3f9adfd4bbff3f9cf725f66d2e1854c1d9d2180ef422daf9c594c319a0ffce5b", + ".straymark/hooks/pre-pr.sh": "dcc25301efc70123e9afdfa33a7de175a45abc3edd72eb1ff6cb414ad92b83df", + ".straymark/templates/i18n/zh-CN/TEMPLATE-AILABEL.md": "c60d8b9cfff6732928c85e1db1cf81ffc3f5cac006865bf5f454db152281d4d9", + ".straymark/templates/TEMPLATE-SEC.md": "233afc81358b9b9aabad8634b50b4a8577d6eec0e2393cfad14af7a4a3cac380", + ".straymark/templates/charter/charter-template.md": "a8abe7e8e7d924fdc06ce3783a6f8933cda2810426fb5068af4ad134ae1bab23", + ".straymark/templates/TEMPLATE-TC260RA.md": "8c0ef4be7a9c9811d3c3dee8262270cc5d3501c88cb1c798f8d7f4038429df71", + ".straymark/templates/i18n/es/TEMPLATE-MCARD.md": "cc4b9587b03e5a400e024f012932de8f1ff6bf1deef5e86f58e5bd1a9310893f", + ".straymark/03-implementation/NIST-AI-RMF-MEASURE-GUIDE.md": "0b2c5e6704b0aa51abebd4982ac739466a0949424204ba4929055b8a7a351423", + ".straymark/templates/TEMPLATE-AILABEL.md": "bd80dc0e46b29b035fed3a6fa072d8d6b10bf4e9a9c2143a456177b6495f05ae", + ".straymark/00-governance/ISO-25010-2023-REFERENCE.md": "28641b79cef89279abb6ce8bf00fae3b909524965920828b7517a80dc22a3dd0", + ".straymark/00-governance/i18n/es/AGENT-RULES.md": "e46fb6197ea90c7a226a55adabaac5b393acdbee67305c36ee9432b97dfb670d", + ".straymark/05-operations/incidents/.gitkeep": "a0face4379a29d0f518afeb57eb4a1e6f1b6025d38ca02b06ee0fac6febfdfdc", + ".straymark/03-implementation/i18n/es/NIST-AI-RMF-MEASURE-GUIDE.md": "9e68b6a0c4bb191c970ad3efe384c37c9556cdcf3b3cf6fb33b13dae14545cf4", + ".straymark/templates/i18n/es/TEMPLATE-DPIA.md": "7690eefdb6a1592fe4d642f6242cdf7ad2a651c403e175c0282abdf3459b362b", + ".straymark/templates/i18n/zh-CN/TEMPLATE-REQ.md": "12b88923720af80f77910699fedfe80d798131612fe824a592d93334c03169f7", + ".straymark/00-governance/DOCUMENTATION-POLICY.md": "2dc79bf3f45fd970125f42999f7bc7131c42e2451bd566bae613e8bcd4909db4", + ".straymark/templates/i18n/es/TEMPLATE-AILOG.md": "f9a16d52eb91be70e8f05fa86e40643ac1ce51eadabcbeecbfc60d7180a8702b", + ".straymark/00-governance/i18n/es/AI-KPIS.md": "a1ffca74c637f33ee57ba929390479c4f8ffce0eeab5182cc9702bdba1ddc27d", + ".straymark/00-governance/i18n/es/GIT-BRANCHING-STRATEGY.md": "e2d0b91577d5a3df99858c5df25cfd76a887e46b7a6cf40058df50ab3b9475db", + ".straymark/00-governance/i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md": "2459da4e66046fcf476e831dfebefcc46a5deefc3f2a1ea75ad1295d984a97c1", + ".straymark/00-governance/i18n/zh-CN/AGENT-RULES.md": "eeee7e939e900c0f5bfbdddff9cf18d99f223605468c78af32888006d0f053e9", + ".straymark/scripts/check-charter-drift.sh": "a5f4eb92dab38ef4bb96492b994ee37beb90bffa441e5f2331d3b71058460c74", + ".straymark/00-governance/AI-LIFECYCLE-TRACKER.md": "39267295031e2ad3b1470bdb591b0c0ab8ae39f26524dcc01d7264bf15e704c2", + ".straymark/templates/i18n/zh-CN/TEMPLATE-DPIA.md": "c5b4a8ccf766cd9e9d2b54b453bd8188d0c06f9af4659805335f9f6b30a545b7", + ".straymark/00-governance/i18n/es/OBSERVABILITY-GUIDE.md": "b1198fc690eaba122b246a6951743edd9fd1d91f095a4369c0a6a13c21848eee", + ".straymark/00-governance/i18n/zh-CN/ISO-25010-2023-REFERENCE.md": "0007111673a3901cd0ef8e7c182be853cdb3d2b9b5e8e87d7cca71bbb2479d7e", + ".straymark/templates/TEMPLATE-DPIA.md": "526f2bc1fe4449138fb3a80bfd8c9bde432d2c0e48ccb14003734f0fba2119ef", + ".straymark/templates/TEMPLATE-PIPIA.md": "420c38163c61bfc04fd6909218fa44b5b94a33c63a9d9e4cc24185eb0e489ba5", + ".straymark/00-governance/OBSERVABILITY-GUIDE.md": "43cc4ef2ac9f3f959748095de398c1e3e0bc5af3b0bcfc01a8e8f65686c916d1", + ".straymark/templates/TEMPLATE-TES.md": "ac97cf9426d3ce9808b35c1bae75f02a6a3fe0653401864161ba878a74460112", + ".straymark/00-governance/MANAGEMENT-REVIEW-TEMPLATE.md": "2c789489a83c2def1c869c344186fbac5d1ba9c18f431e32711e740a2f0246b3", + ".straymark/07-ai-audit/agent-logs/AILOG-2026-04-02-001-add-git-operations-rules-claude-md.md": "1006edb4fc51e3756807710009eda4939a90be182d2cde2f6849327d9b9b78e3", + ".straymark/templates/TEMPLATE-AILOG.md": "9ab5eb8131285dbf37fdd7fb92d0376bfb99cf506432f562c3c490ea96ce4135", + ".straymark/00-governance/TC260-IMPLEMENTATION-GUIDE.md": "b872176b2c69024c64d8642aa495e98c92ed0c06cb4d1b38bea3aaa141bd785e", + ".straymark/templates/i18n/es/TEMPLATE-SBOM.md": "91405d08eb76c063be7b245e73b79c833f9cf9ad6e1c1290675593bd476c974c", + ".straymark/04-testing/TES-2026-04-03-001-cli-integration-test-coverage.md": "b0cf161975f5fc4001de3ab9fb717af360e02b05f2af04e433c27774dd60db42", + ".straymark/00-governance/i18n/es/AI-GOVERNANCE-POLICY.md": "95bbda3ae9825b40b09173774e14a37b54b6c4838208b8a3bca00b3e9fe524c1", + ".straymark/03-implementation/NIST-AI-RMF-MANAGE-GUIDE.md": "dc336008b7e8af796b0698e9f6f9561ffa64659d1315611ae0d7106dd9408c2e", + ".straymark/templates/i18n/es/TEMPLATE-ADR.md": "a1c654bd1a999f5e874c59ddc406179cb1f4ada98bec606355197bcba19c468a", + ".straymark/schemas/audit-output.schema.v0.json": "4c8d857b7ac77a64056dacaba4bbbe86a3a80ccac087797ae5527e18febfa28a", + ".straymark/templates/TEMPLATE-INC.md": "1c7c35e1c1124b0b3511b78ba73ae6f6ee16e671b41e3f541f1f68cf37aff2ba", + ".straymark/templates/i18n/es/TEMPLATE-REQ.md": "05df6fda9689f10f5686133c053de0690f7e5f2c987ed54449c522386e010803", + ".straymark/dist-manifest.yml": "a6fb8bce9246953713924699300b48d40c673c6d29f905d714dfaf521371b083", + ".straymark/templates/i18n/zh-CN/TEMPLATE-SBOM.md": "0c0294b3981ea6fa21357aaf619a3117b607b87e1b814386566c7ed0e03f34b1", + ".straymark/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md": "ba3acf0d03bfc93c91869fe8f83ab2c5bf5548a5a5601dd25970113046181d3c", + ".straymark/00-governance/i18n/zh-CN/MANAGEMENT-REVIEW-TEMPLATE.md": "50edbc0de0c2f1096432ea4330acad2b909a0408d3ee011581185dcbb83678f1", + ".straymark/00-governance/i18n/zh-CN/PRINCIPLES.md": "9680cbaf0b3eabfa22d390e637ee7c6a7a599335aa4b819929c40013f862a43e", + ".straymark/00-governance/i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md": "a5c601f7503a28c58b16d88b5d441b540baf16897886f5a592882d31d98032fb", + ".straymark/00-governance/i18n/zh-CN/EMERGENT-OBSERVATION-DESIGN.md": "bf6cda8e77da432827d4969595f1cfe643d7d95efc4cf9aab0a8062c187edd1e", + ".straymark/02-design/decisions/.gitkeep": "d268c27da8232243534ae5dbcbfc52629f1112c2bfc018462a41fbe1a233b164", + ".straymark/03-implementation/i18n/es/NIST-AI-RMF-MAP-GUIDE.md": "7147d6e6bcc57b188984f8f532904c545c74c19883947127ca7b03d7b957e28c", + ".straymark/00-governance/i18n/zh-CN/GIT-BRANCHING-STRATEGY.md": "8c3c3b1815fcc15a8a8608bc791135da00b39f6a28028dd66a5aad630f58c9a3", + ".straymark/07-ai-audit/SBOM-2026-04-03-001-self-update-dependency.md": "6196ad542bcd860c26364436676f0160f25477debb3c676c8ca227dc4e551282", + ".straymark/audit-prompts/i18n/es/audit-prompt.md": "2ef095a7e15e70ae2a23e53fc62b0444835c18aebbf5616bcfc2d3425e60c8ce", + ".straymark/00-governance/EMERGENT-OBSERVATION-DESIGN.md": "8bcf1762b152bced068cfcd3d7094402a690d450f795f1e7993d4d7218487878", + ".straymark/03-implementation/NIST-AI-RMF-MAP-GUIDE.md": "5250919126a82e6e1fcbb138d07c9cf6032dfa7b65982be2624b7301f4a1e660", + ".straymark/templates/i18n/zh-CN/TEMPLATE-TC260RA.md": "4440a8b052a00e3ced4894a6860b67f4642a8bf02b1fc0ad2855c00f3c5ffdaa", + ".straymark/templates/TEMPLATE-TDE.md": "87a95beebe0f46c853650e3a49fb7e4d32a1b2cb1a663599431b2c10bd0be7d1", + ".straymark/00-governance/FOLLOW-UPS-BACKLOG-PATTERN.md": "8cdf0df39532b564c445538e43b320b154df47e59c0b113f0b7fd3bada46346f", + ".straymark/01-requirements/.gitkeep": "b87527d29d1ec75b950d6b5fcdac2063a5426486c2cabee43841e1fb2780190c", + ".straymark/templates/i18n/es/TEMPLATE-INC.md": "85c72cfcdf8ffe1a90654fbb92e9617ae039945ca6b400a326ae93a0eca460bd", + ".straymark/00-governance/PRINCIPLES.md": "116d0ceb81d5ae41fa3a654d7a056c29510566bfe59aa3beae735c02ce3f9d96" + } +} \ No newline at end of file diff --git a/.straymark/00-governance/AGENT-RULES.md b/.straymark/00-governance/AGENT-RULES.md new file mode 100644 index 0000000..a842552 --- /dev/null +++ b/.straymark/00-governance/AGENT-RULES.md @@ -0,0 +1,390 @@ +# Rules for AI Agents - StrayMark + +> This document defines the rules that all AI agents must follow when working on projects under StrayMark. + +**Languages**: English | [Español](i18n/es/AGENT-RULES.md) | [简体中文](i18n/zh-CN/AGENT-RULES.md) + +--- + +## 1. Mandatory Identification + +### When Starting a Session + +Every agent must identify themselves with: +- Agent name (e.g.: `claude-code-v1.0`, `cursor-v1.0`, `gemini-cli-v1.0`) +- Agent version if available + +### In Every Document + +Include in the frontmatter: +```yaml +agent: agent-name-v1.0 +confidence: high | medium | low +``` + +--- + +## 2. When to Document + +### MANDATORY - Create document + +| Situation | Type | Notes | +|-----------|------|-------| +| Code complexity above threshold | AILOG | Run `straymark analyze --output json`. If `summary.above_threshold > 0`, create AILOG (default threshold: 8). **Fallback**: if CLI unavailable, apply >20 lines of business logic heuristic | +| Decision between 2+ technical alternatives | AIDEC | Document alternatives | +| Changes in auth/authorization/PII | AILOG + ETH | `risk_level: high`, ETH requires approval | +| Changes in public API or DB schema | AILOG | `risk_level: medium+`, consider ADR | +| Changes in ML models or AI prompts | AILOG | `risk_level: medium+`, human review required | +| Integration with external service | AILOG | - | +| Addition/removal/upgrade of security-critical dependencies | AILOG | Human review required | +| Changes affecting AI system lifecycle (deployment, retirement) | AILOG + ADR | Human review required | +| Changes to OTel instrumentation (spans, attributes, pipeline) | AILOG | Tag `observabilidad`, see §9 | +| Transversal technical debt discovered during implementation | TDE | See §3 "TDE vs `R` (new, not in Charter)" for the disambiguation criterion | + +### PROHIBITED - Do not document + +- Credentials, tokens, API keys +- Personally identifiable information +- Secrets of any kind + +### OPTIONAL - Does not require document + +- Formatting changes (whitespace, indentation) +- Typo corrections +- Code comments +- Minor style changes + +--- + +## 3. Autonomy Limits + +### Create Freely + +| Type | Description | +|------|-------------| +| AILOG | Logs of actions performed | +| AIDEC | Technical decisions made | + +### Create Draft → Requires Human Approval + +| Type | Description | +|------|-------------| +| ETH | Ethical reviews | +| ADR | Architectural decisions | + +### Propose → Requires Human Validation + +| Type | Description | +|------|-------------| +| REQ | System requirements | +| TES | Test plans | + +### Create Draft → Requires Human Approval (new types) + +| Type | Description | +|------|-------------| +| SEC | Security assessments (`review_required: true` always) | +| MCARD | Model/System cards (`review_required: true` always) | +| DPIA | Data Protection Impact Assessments (`review_required: true` always) | + +### Create Freely (new types) + +| Type | Description | +|------|-------------| +| SBOM | Software Bill of Materials (factual inventory) | + +### Identify Only → Human Prioritizes + +| Type | Description | +|------|-------------| +| TDE | Technical debt | +| INC | Incident conclusions | + +### TDE vs `R (new, not in Charter)` + +Two surfaces exist for emergent debt. They are not interchangeable — pick the one whose lifecycle matches the work, not whichever is closer to hand. + +**File an `R (new, not in Charter)` entry in the AILOG `§Risk` section** when the debt: + +- Is *scoped to the Charter currently in execution* or the next Charter in sequence. +- Resolves as a documented deferral, a small atomic fix, or a forward-pointer to a Charter that already exists. +- Carries low-to-medium impact and the agent can describe the remediation in one bullet. + +**Create a TDE document** when the debt: + +- Is *heritage from a prior Charter*. Two distinct shapes both qualify (both are TDE-worthy): + - **Strict heritage** — a prior Charter introduced the debt; subsequent Charters merely propagate it without re-introducing the underlying decision (e.g., a legacy DB schema choice; an early auth shortcut; a deferred config decision). The current Charter inherits the debt by transitive contact. + - **Pattern propagation** — a prior Charter set a pattern that subsequent Charters *re-introduce* by following it. The current Charter doesn't merely propagate; it re-creates the same debt by replicating the pattern (e.g., handler shape that omits `RequireScope`, test scaffolding that bypasses HTTP middleware). The fix is at the pattern level, not at any single Charter. +- *Applies to multiple modules **or Charter execution boundaries*** — fragmenting it into per-Charter `R` entries loses the architectural shape. "Charter execution boundaries" captures governance-trail debt that spans sessions without spanning code modules: e.g., a deferred classification in CHARTER-04 that passes silently through CHARTER-08 → CHARTER-13 and only surfaces under a fresh CI gate. +- *Requires a dedicated Charter outside the current scope envelope* to remediate (not the current Charter, not the next one). +- *Requires human prioritization or assignment* the agent cannot decide alone (impact × effort matrix, ownership, sprint placement). + +The four triggers above are the activation criteria for TDE under §2. When the AILOG you are about to write would carry an `R` matching any of them, write the TDE instead and reference it from the AILOG `§Risk` row. + +--- + +## 4. When to Request Human Review + +Mark `review_required: true` when: + +1. **Low confidence**: `confidence: low` +2. **High risk**: `risk_level: high | critical` +3. **Security decisions**: Any change in auth/authz +4. **Irreversible changes**: Migrations, deletions +5. **User impact**: Changes affecting UX +6. **Ethical concerns**: Privacy, bias, accessibility +7. **ML model changes**: Changes to model parameters, architecture, or training data +8. **AI prompt changes**: Modifications to prompts or agent instructions +9. **Security-critical dependencies**: Addition, removal, or upgrade of security-sensitive packages +10. **AI lifecycle changes**: Deployment, retirement, or major version changes of AI systems + +--- + +## 5. Document Format + +### Use Templates + +Before creating a document, load the corresponding template: + +``` +.straymark/templates/TEMPLATE-[TYPE].md +``` + +### Naming Convention + +``` +[TYPE]-[YYYY-MM-DD]-[NNN]-[description].md +``` + +### Location + +| Type | Folder | +|------|--------| +| AILOG | `.straymark/07-ai-audit/agent-logs/` | +| AIDEC | `.straymark/07-ai-audit/decisions/` | +| ETH | `.straymark/07-ai-audit/ethical-reviews/` | +| ADR | `.straymark/02-design/decisions/` | +| REQ | `.straymark/01-requirements/` | +| TES | `.straymark/04-testing/` | +| INC | `.straymark/05-operations/incidents/` | +| TDE | `.straymark/06-evolution/technical-debt/` | +| SEC | `.straymark/08-security/` | +| MCARD | `.straymark/09-ai-models/` | +| SBOM | `.straymark/07-ai-audit/` | +| DPIA | `.straymark/07-ai-audit/ethical-reviews/` | + +### Tags and Related + +When populating the `tags` and `related` fields in frontmatter: + +**Tags:** +- Use kebab-case keywords: `sqlite`, `api-design`, `gnome-integration` +- 3 to 8 tags per document describing topic, technology, or component +- Tags enable search and categorization in `straymark explore` + +**Related:** +- Reference other **StrayMark documents only** — use the document filename with `.md` extension +- If the document is in a subdirectory within `.straymark/`, include the relative path: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-file.md` +- If the document is in the same directory, the filename alone is sufficient +- **Do not** put task IDs (T001, US3), issue numbers, or external URLs in `related` — put those in the document body instead + +--- + +## 6. Communication with Humans + +### Be Transparent + +- Explain the reasoning behind decisions +- Document considered alternatives +- Admit uncertainty when it exists + +### Be Concise + +- Get to the point +- Avoid unnecessary jargon +- Use lists and tables when appropriate + +### Be Proactive + +- Identify potential risks +- Suggest improvements when evident +- Alert about technical debt +- **Surface dissonance between canonical sources** (Principle #8 — see [`PRINCIPLES.md`](PRINCIPLES.md)). When the agent detects material divergence between two canonical sources of StrayMark documentation, raise it before proceeding with the asked task. Examples to watch for during routine work: + - Spec stale relative to shipped code in long-running multi-Charter chains (see [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 1) + - Accumulated `R (new, not in Charter)` entries that match TDE criteria but were not escalated (see §3 above) + - ADR vigente contradicted by current implementation + - `§Follow-ups` count crossing the backlog-pattern threshold (see [`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md)) + - Audit findings emerging post-close that warrant amendment (see [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 2) + + See [`EMERGENT-OBSERVATION-DESIGN.md`](EMERGENT-OBSERVATION-DESIGN.md) for the meta-pattern that ties these surfaces together. + +--- + +## 7. Error Handling + +If the agent makes an error: + +1. **Document** the error in an AILOG +2. **Explain** what went wrong +3. **Propose** correction +4. **Mark** `review_required: true` + +--- + +## 8. Document Updates + +### Create New vs Update + +| Situation | Action | +|-----------|--------| +| Minor correction | Update existing document | +| Significant change | Create new document | +| Obsolete document | Mark as `deprecated` | +| Complete replacement | Create new + mark previous as `superseded` | + +### When Updating + +- Update the `updated` field in frontmatter +- Add a note in the history section if it exists +- Maintain consistency with related documents + +--- + +## 9. Observability (OpenTelemetry) + +When working on projects that use OpenTelemetry: + +### Rules + +- **Do not** capture PII, tokens, or secrets in OTel attributes or logs +- **Record** instrumentation pipeline changes (new spans, changed attributes, Collector configuration) in AILOG with tag `observabilidad` +- **Create** AIDEC or ADR when adopting OTel in distributed projects — document the adoption decision and backend selection +- **Set** `observability_scope` in frontmatter when the change involves OTel instrumentation + +### Documentation Triggers + +| Change | Document | Additional | +|--------|----------|-----------| +| New spans or changed attributes | AILOG | Tag `observabilidad` | +| OTel backend selection | AIDEC or ADR | If distributed system | +| Collector pipeline configuration | AILOG | Tag `observabilidad` | +| Sampling strategy changes | AIDEC | Document rationale | +| Observability requirements | REQ | Use Observability Requirements section | +| Trace propagation tests | TES | Use Observability Tests section | +| Incident with trace evidence | INC | Include trace_id/span_id in timeline | +| Instrumentation debt | TDE | Tag `observabilidad` | + +--- + +## 10. Architecture Diagrams (C4 Model) + +When creating ADR documents that involve architectural changes: + +- **Include** a Mermaid C4 diagram at the appropriate level +- **Use** `C4Context` for system-level decisions (who uses the system, external dependencies) +- **Use** `C4Container` for service/container-level decisions (applications, databases, message queues) +- **Use** `C4Component` for internal module decisions (components within a service) +- **See** `00-governance/C4-DIAGRAM-GUIDE.md` for syntax reference and examples + +> Diagrams are optional for minor decisions. Use them when the decision changes system boundaries, introduces new services, or modifies inter-service communication. + +--- + +## 11. API Specification Tracking + +When a change modifies API endpoints: + +- **Verify** that the corresponding OpenAPI or AsyncAPI specification is updated +- **Reference** the spec path in the AILOG or ADR using the `api_spec_path` field (in REQ) or `api_changes` field (in ADR) +- **Document** breaking API changes in an ADR with `risk_level: high` + +--- + +## 12. Audit Checkpoint (Charter workflow) + +When co-implementing a Charter, the agent **proactively offers** an external multi-model audit at a specific moment in the workflow. The checkpoint is **soft** — it never blocks `charter close` and is never escalated to enforcement. External audit is opt-in by design (cost, trust in the operator's primary discipline). + +### When to emit the checkpoint + +Emit the checkpoint **once per Charter** when **all four** triggers are simultaneously true: + +1. The Charter is in status `in-progress` or `declared` (not `closed`). +2. All tasks in the Charter's `## Tasks` section are marked `[x]` complete (or the agent just completed the last one). +3. `straymark charter drift ` exits 0 (no unaccounted drift). +4. The developer has **not** invoked `straymark charter close ` yet, nor mentioned intent to close. + +If the developer declined audit on a previous turn for the same Charter, **do not re-emit** in subsequent turns of the same conversation. + +### Form of the checkpoint message + +Render the message like this (substitute `` and the recommendation reasoning): + +``` +Reached the checkpoint for . Implementation is done, drift +check is clean, only `straymark charter close` is pending. + +At this point you can run an external audit (typically 2 LLMs of +different families + a calibrator) that produces cross-model findings +on the implementation. + +My recommendation: [YES / NO], because: + - + +If you decide to audit: + Run /straymark-audit-prompt and I will write the unified + audit prompt to .straymark/audits//audit-prompt.md. + Then open one or more auditor-side CLIs (gemini-cli, claude-cli, + copilot-cli, codex-cli) in this repo and invoke + /straymark-audit-execute in each — recommendation: at + least 2 auditors of different model families. When and only when + ALL auditors you commissioned have completed, return here and run + /straymark-audit-review . I will consolidate the N + reports into a review.md document with verdicts, remediation plan, + and auditor ratings, and merge the YAML block into the Charter + telemetry. + +If you decide not to audit: + Continue with `straymark charter close ` when you're + ready. External audit is fully optional — StrayMark's declarative + Charter + drift check + AILOG discipline gives the cycle enough + rigor for confident close without it. +``` + +### Heuristics for the YES/NO recommendation + +These are heuristics, not rigid rules — you are close to the context, refine them with the adopter. + +**Recommend YES when** (any one suffices): + +- The Charter touched security-critical surface (auth, RLS, secret handling, IAM). +- The Charter introduced a new component (not a refactor) that the developer has not co-implemented before. +- An associated AILOG documents an `R` with `confidence: low | medium` and `risk_level: medium` or higher. +- The developer marked the Charter as `effort_estimate: L` and this is the adopter's first Charter. +- The developer **explicitly** asked for cross-model validation in the Charter trigger. +- **Structural complexity signal** *(only when the CLI was compiled with the `analyze` feature, true for official binaries)*: the diff in `range` introduces or modifies at least one function whose cognitive complexity exceeds **2× the configured threshold** in `.straymark/config.yml` (`complexity.threshold`, default `8` → ≥ `17`). A dense new function is exactly the case where two cross-family auditors capture implementation gaps that a single model misses. **Graceful-degradation:** if the binary lacks the `analyze` feature, silently skip this signal — do not warn, do not mention. + +**Recommend NO when** (all of these together): + +- The Charter is a refactor or documentation change (no new behavior). +- `effort_estimate` is `XS` or `S`. +- Associated AILOGs all have `confidence: high` and no emergent `R` risks. +- The Charter's `risk_level` is `low` (or unset). + +**Default case (no clear signal either way):** recommend **NO** with neutral framing ("I don't see a specific signal that justifies the cost of two additional models; close when you're ready"). The cost of external audit is real — do not inflate adoption by recommending YES on inertia. + +### Rules of engagement + +- The checkpoint is **never** repeated within the same Charter once the developer responds. +- The checkpoint **does not** block any subsequent action. If the developer ignores it and runs `charter close`, close proceeds normally — there is no enforcement and there will not be (this is a permanent v0+v1 design decision; see `Propuesta/straymark-audit-skills.md` §2.2). +- The checkpoint is **not** counted in any quality metric. There is no "% Charters audited" KPI in `straymark metrics` — by design, to avoid creating an incentive to inflate the audit count. +- If the developer accepts the audit, the workflow proceeds via three skills in sequence: `/straymark-audit-prompt` (writes the unified prompt at the canonical path) → `/straymark-audit-execute` × N (one per auditor-side CLI the operator opens — these run in those CLIs, not in the main agent) → `/straymark-audit-review` (consolidates N reports inline into `.straymark/audits//review.md` and merges the YAML into telemetry). Operators never copy/paste prompts or reports — file exchange happens via canonical paths under `.straymark/audits/`. + +--- + +## Patterns + +When a project accumulates a high volume of AILOGs across multiple Charters and follow-ups become hard to track, see [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) for a reproducible convention (central registry + drift detection script + agent integration). Adopters at ~20+ AILOGs benefit; below that threshold the per-AILOG `§Follow-ups` convention alone is sufficient. + +--- + +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.devtrail/00-governance/AI-GOVERNANCE-POLICY.md b/.straymark/00-governance/AI-GOVERNANCE-POLICY.md similarity index 78% rename from .devtrail/00-governance/AI-GOVERNANCE-POLICY.md rename to .straymark/00-governance/AI-GOVERNANCE-POLICY.md index bca291e..e50ef09 100644 --- a/.devtrail/00-governance/AI-GOVERNANCE-POLICY.md +++ b/.straymark/00-governance/AI-GOVERNANCE-POLICY.md @@ -2,7 +2,7 @@ > **Aligned with**: ISO/IEC 42001:2023 — Artificial Intelligence Management System (AIMS) > -> This document provides a governance template for organizations using DevTrail. It maps ISO 42001 clauses to DevTrail document types, enabling teams to build compliance-ready documentation as part of their development workflow. +> This document provides a governance template for organizations using StrayMark. It maps ISO 42001 clauses to StrayMark document types, enabling teams to build compliance-ready documentation as part of their development workflow. > > **This is a template** — adapt each section to your organization's context. @@ -31,15 +31,21 @@ ### 1.3 Legal and Regulatory Requirements -| Regulation | Applicable | Status | DevTrail Evidence | +| Regulation | Applicable | Status | StrayMark Evidence | |-----------|-----------|--------|-------------------| | EU AI Act | [Yes/No] | [Compliant/In progress/Gap] | ETH, MCARD | | GDPR | [Yes/No] | [Status] | ETH (Data Privacy), DPIA | | NIST AI RMF | [Yes/No] | [Status] | AI-RISK-CATALOG | | ISO/IEC 42001 | [Yes/No] | [Status] | This document | +| TC260 AI Safety Governance Framework v2.0 *(China)* | [Yes/No] | [Status] | TC260RA | +| PIPL / PIPIA *(China)* | [Yes/No] | [Status] | PIPIA, ETH (Data Privacy) | +| GB 45438-2025 — AI Content Labeling *(China, mandatory)* | [Yes/No] | [Status] | AILABEL, MCARD | +| CAC Algorithm Filing *(China)* | [Yes/No] | [Status] | CACFILE | +| GB/T 45652-2025 — Training Data Security *(China)* | [Yes/No] | [Status] | SBOM, MCARD | +| CSL 2026 Incident Reporting *(China)* | [Yes/No] | [Status] | INC | | [Other] | [Yes/No] | [Status] | [Documents] | -> **DevTrail mapping**: REQ documents capture regulatory requirements. ETH documents assess compliance gaps. +> **StrayMark mapping**: REQ documents capture regulatory requirements. ETH documents assess compliance gaps. China rows are exposed only when `regional_scope: china` is enabled in `.straymark/config.yml` — see [CHINA-REGULATORY-FRAMEWORK.md](CHINA-REGULATORY-FRAMEWORK.md). --- @@ -59,7 +65,7 @@ ### 2.2 Roles and Responsibilities -| Role | Responsibilities | DevTrail Mapping | +| Role | Responsibilities | StrayMark Mapping | |------|-----------------|------------------| | AI Governance Lead | Overall AIMS management, policy maintenance | This document, MANAGEMENT-REVIEW-TEMPLATE | | Development Team | Documentation, implementation, testing | AILOG, AIDEC, TES | @@ -75,7 +81,7 @@ - [ ] Resources allocated for AI governance - [ ] Regular management reviews scheduled -> **DevTrail mapping**: ADR documents record governance decisions. AGENT-RULES.md defines agent autonomy limits. +> **StrayMark mapping**: ADR documents record governance decisions. AGENT-RULES.md defines agent autonomy limits. --- @@ -85,7 +91,7 @@ ### 3.1 Risk Identification -| Risk Category | Description | Likelihood | Impact | Current Controls | DevTrail Evidence | +| Risk Category | Description | Likelihood | Impact | Current Controls | StrayMark Evidence | |--------------|-------------|-----------|--------|-----------------|-------------------| | Bias / Fairness | [Description] | [H/M/L] | [H/M/L] | [Controls] | ETH (Bias section) | | Privacy | [Description] | [H/M/L] | [H/M/L] | [Controls] | ETH (Privacy), DPIA | @@ -96,15 +102,15 @@ > **Reference**: See AI-RISK-CATALOG.md for the full risk catalog mapped to NIST AI 600-1 categories. > -> **DevTrail mapping**: ETH documents assess individual risks. AI-RISK-CATALOG.md consolidates the organizational risk register per ISO 42001 Annex A.5. +> **StrayMark mapping**: ETH documents assess individual risks. AI-RISK-CATALOG.md consolidates the organizational risk register per ISO 42001 Annex A.5. ### 3.2 AI Objectives | Objective | Target | Measurement | Timeline | Owner | |-----------|--------|-------------|----------|-------| -| Documentation coverage | [e.g., 100% of significant changes documented] | `devtrail metrics` | [Date] | [Owner] | -| Review compliance | [e.g., All high-risk docs reviewed within 5 days] | `devtrail metrics` | [Date] | [Owner] | -| Risk assessment coverage | [e.g., ETH for all high-risk changes] | `devtrail compliance` | [Date] | [Owner] | +| Documentation coverage | [e.g., 100% of significant changes documented] | `straymark metrics` | [Date] | [Owner] | +| Review compliance | [e.g., All high-risk docs reviewed within 5 days] | `straymark metrics` | [Date] | [Owner] | +| Risk assessment coverage | [e.g., ETH for all high-risk changes] | `straymark compliance` | [Date] | [Owner] | ### 3.3 Planning for Changes @@ -125,8 +131,8 @@ When significant changes affect the AI management system: | Resource | Description | Status | |----------|-------------|--------| -| DevTrail Framework | Documentation governance system | [Installed/Version] | -| DevTrail CLI | Automation and validation tools | [Version] | +| StrayMark Framework | Documentation governance system | [Installed/Version] | +| StrayMark CLI | Automation and validation tools | [Version] | | AI Agent Platforms | [Claude, Gemini, Copilot, Cursor] | [Configured] | | Training | AI governance training for team | [Status] | @@ -134,7 +140,7 @@ When significant changes affect the AI management system: | Role | Required Competencies | Training Plan | |------|----------------------|---------------| -| Developers | DevTrail usage, AI ethics basics, regulatory awareness | [Plan] | +| Developers | StrayMark usage, AI ethics basics, regulatory awareness | [Plan] | | AI Agents | AGENT-RULES.md compliance, template usage | [Directive configuration] | | Reviewers | Risk assessment, EU AI Act requirements, ISO 42001 basics | [Plan] | @@ -148,18 +154,18 @@ All team members must be aware of: ### 4.4 Communication -| What | To Whom | When | Method | DevTrail Record | +| What | To Whom | When | Method | StrayMark Record | |------|---------|------|--------|----------------| | Policy updates | All team | On change | [Method] | ADR | -| Risk assessments | Reviewers | Per ETH creation | DevTrail notification | ETH | +| Risk assessments | Reviewers | Per ETH creation | StrayMark notification | ETH | | Incident reports | Management | Within 24h | [Method] | INC | -| Governance metrics | Management | [Monthly/Quarterly] | `devtrail metrics` | Metrics report | +| Governance metrics | Management | [Monthly/Quarterly] | `straymark metrics` | Metrics report | ### 4.5 Documented Information -DevTrail serves as the documented information system for the AIMS. Key documents: +StrayMark serves as the documented information system for the AIMS. Key documents: -| ISO 42001 Requirement | DevTrail Document | +| ISO 42001 Requirement | StrayMark Document | |----------------------|-------------------| | AI Policy | This document (§2) | | Risk Assessment | ETH, AI-RISK-CATALOG.md | @@ -175,7 +181,7 @@ DevTrail serves as the documented information system for the AIMS. Key documents ### 5.1 Lifecycle Phases -| Phase | Activities | DevTrail Documents | ISO 42001 Control | +| Phase | Activities | StrayMark Documents | ISO 42001 Control | |-------|-----------|-------------------|-------------------| | Design | Requirements, architecture decisions | REQ, ADR, AIDEC | A.6.2.2 | | Development | Implementation, code changes | AILOG, AIDEC | A.6.2.2, A.6.2.9 | @@ -193,7 +199,7 @@ Per AGENT-RULES.md, documentation is required when: - Changes affect auth/authorization/PII → AILOG + ETH draft - Changes in public API or DB schema → AILOG - Changes in ML models or AI prompts → AILOG + human review -- Code above cognitive complexity threshold (run `devtrail analyze`; fallback: >20 lines) → AILOG +- Code above cognitive complexity threshold (run `straymark analyze`; fallback: >20 lines) → AILOG - Decision between 2+ alternatives → AIDEC - Security-critical dependency changes → AILOG + human review @@ -203,7 +209,7 @@ Per AGENT-RULES.md, documentation is required when: |-----------|----------|---------|-----------|------------| | [Component] | [Provider] | [Purpose] | [H/M/L] | [Date] | -> **DevTrail mapping**: SBOM documents AI supply chain. ETH assesses third-party risks. +> **StrayMark mapping**: SBOM documents AI supply chain. ETH assesses third-party risks. --- @@ -215,9 +221,9 @@ Per AGENT-RULES.md, documentation is required when: | KPI | Target | Measurement Method | Frequency | |-----|--------|-------------------|-----------| -| Documentation coverage | [Target %] | `devtrail metrics` | [Frequency] | -| Review completion rate | [Target %] | `devtrail metrics` | [Frequency] | -| Mean time to document | [Target days] | `devtrail metrics` | [Frequency] | +| Documentation coverage | [Target %] | `straymark metrics` | [Frequency] | +| Review completion rate | [Target %] | `straymark metrics` | [Frequency] | +| Mean time to document | [Target days] | `straymark metrics` | [Frequency] | | High-risk doc review time | [Target days] | Manual tracking | [Frequency] | | Incident documentation | [Target %] | INC count vs incidents | [Frequency] | @@ -227,7 +233,7 @@ Per AGENT-RULES.md, documentation is required when: - **Frequency**: [e.g., Quarterly] - **Scope**: Compliance with this policy, AGENT-RULES.md, and regulatory requirements -- **Method**: `devtrail compliance --all` + manual review +- **Method**: `straymark compliance --all` + manual review - **Auditor**: [Role/Name] ### 6.3 Management Review @@ -256,10 +262,10 @@ When a nonconformity is identified: ### 7.2 Improvement Sources -| Source | DevTrail Input | Action | +| Source | StrayMark Input | Action | |--------|---------------|--------| -| Validation failures | `devtrail validate` errors | Fix and document | -| Compliance gaps | `devtrail compliance` report | Plan remediation | +| Validation failures | `straymark validate` errors | Fix and document | +| Compliance gaps | `straymark compliance` report | Plan remediation | | Incident post-mortems | INC documents | Implement corrective actions | | Management reviews | Review meeting outputs | Update policy/objectives | | Agent feedback | AILOG with suggestions | Evaluate and prioritize | @@ -267,11 +273,11 @@ When a nonconformity is identified: --- -## Annex: ISO 42001 Annex A Controls → DevTrail Mapping +## Annex: ISO 42001 Annex A Controls → StrayMark Mapping -> This mapping enables teams to demonstrate Annex A control coverage through DevTrail documentation. +> This mapping enables teams to demonstrate Annex A control coverage through StrayMark documentation. -| Topic Area | Control | ID | DevTrail Document(s) | +| Topic Area | Control | ID | StrayMark Document(s) | |-----------|---------|-----|---------------------| | **A.2 Policies for AI** | AI Policy | A.2.2 | This document §2 | | | Responsible AI Topics | A.2.3 | This document §2, PRINCIPLES.md | @@ -315,7 +321,7 @@ When a nonconformity is identified: --- -*AI Governance Policy template — DevTrail Framework* +*AI Governance Policy template — StrayMark Framework* *Aligned with ISO/IEC 42001:2023* - + diff --git a/.devtrail/00-governance/AI-KPIS.md b/.straymark/00-governance/AI-KPIS.md similarity index 84% rename from .devtrail/00-governance/AI-KPIS.md rename to .straymark/00-governance/AI-KPIS.md index 5526868..a4faca8 100644 --- a/.devtrail/00-governance/AI-KPIS.md +++ b/.straymark/00-governance/AI-KPIS.md @@ -16,7 +16,7 @@ KPIs serve three functions within the AI management system: - **Accountability**: Provide objective evidence of compliance for audits and reviews - **Improvement**: Identify trends and areas requiring corrective action -> **DevTrail mapping**: Use `devtrail metrics` for automated KPI collection. Results feed into MANAGEMENT-REVIEW-TEMPLATE.md for periodic reviews. +> **StrayMark mapping**: Use `straymark metrics` for automated KPI collection. Results feed into MANAGEMENT-REVIEW-TEMPLATE.md for periodic reviews. --- @@ -27,15 +27,15 @@ KPIs serve three functions within the AI management system: | Field | Value | |-------|-------| | **KPI Name** | Documentation Coverage | -| **Description** | Percentage of AI-related changes that have associated DevTrail documentation (AILOG, AIDEC, ETH, etc.). | +| **Description** | Percentage of AI-related changes that have associated StrayMark documentation (AILOG, AIDEC, ETH, etc.). | | **Target** | > 80% | | **Current Value** | [Measured value] | -| **Measurement Method** | `devtrail metrics` — ratio of documented changes to total AI-related commits | +| **Measurement Method** | `straymark metrics` — ratio of documented changes to total AI-related commits | | **Frequency** | Monthly | | **Owner** | [Development Team Lead] | | **ISO 42001 Reference** | Clause 9.1 (Monitoring, measurement, analysis, and evaluation) | -> **Guidance**: Start with a realistic baseline. Teams new to DevTrail may target 50% initially and increase by 10% per quarter. Changes requiring documentation are defined in AGENT-RULES.md. +> **Guidance**: Start with a realistic baseline. Teams new to StrayMark may target 50% initially and increase by 10% per quarter. Changes requiring documentation are defined in AGENT-RULES.md. --- @@ -47,7 +47,7 @@ KPIs serve three functions within the AI management system: | **Description** | Percentage of documents requiring human review that were reviewed within the defined timeframe. | | **Target** | 100% | | **Current Value** | [Measured value] | -| **Measurement Method** | `devtrail metrics` — ratio of reviewed documents to documents flagged for review | +| **Measurement Method** | `straymark metrics` — ratio of reviewed documents to documents flagged for review | | **Frequency** | Monthly | | **Owner** | [AI Ethics Reviewer] | | **ISO 42001 Reference** | Clause 9.1 (Monitoring, measurement, analysis, and evaluation) | @@ -81,7 +81,7 @@ KPIs serve three functions within the AI management system: | **Description** | Ratio of high and critical risk entries to total entries in the AI-RISK-CATALOG. | | **Target** | < 20% high/critical | | **Current Value** | [Measured value] | -| **Measurement Method** | `devtrail metrics` — count of risks with score >= 10 divided by total risks | +| **Measurement Method** | `straymark metrics` — count of risks with score >= 10 divided by total risks | | **Frequency** | Quarterly | | **Owner** | [Risk Manager] | | **ISO 42001 Reference** | Clause 6 (Planning — Actions to address risks and opportunities) | @@ -95,7 +95,7 @@ KPIs serve three functions within the AI management system: | Field | Value | |-------|-------| | **KPI Name** | Incident Response Time | -| **Description** | Time elapsed from incident detection to creation of a corresponding INC document in DevTrail. | +| **Description** | Time elapsed from incident detection to creation of a corresponding INC document in StrayMark. | | **Target** | < 24 hours | | **Current Value** | [Measured value] | | **Measurement Method** | Compare incident detection timestamp (from monitoring/alerting) with INC document creation date | @@ -112,10 +112,10 @@ KPIs serve three functions within the AI management system: | Field | Value | |-------|-------| | **KPI Name** | Compliance Score | -| **Description** | Overall regulatory compliance percentage as measured by DevTrail's compliance validation engine. | +| **Description** | Overall regulatory compliance percentage as measured by StrayMark's compliance validation engine. | | **Target** | > 75% | | **Current Value** | [Measured value] | -| **Measurement Method** | `devtrail compliance --all` — percentage of passing rules across all applicable regulations | +| **Measurement Method** | `straymark compliance --all` — percentage of passing rules across all applicable regulations | | **Frequency** | Quarterly | | **Owner** | [AI Governance Lead] | | **ISO 42001 Reference** | Clause 9.2 (Internal audit) | @@ -141,8 +141,8 @@ KPIs serve three functions within the AI management system: | Activity | Frequency | Responsible | Output | |----------|-----------|-------------|--------| -| Run `devtrail metrics` | Monthly | [Development Team Lead] | Updated KPI values | -| Run `devtrail compliance --all` | Quarterly | [AI Governance Lead] | Compliance score | +| Run `straymark metrics` | Monthly | [Development Team Lead] | Updated KPI values | +| Run `straymark compliance --all` | Quarterly | [AI Governance Lead] | Compliance score | | Update KPI Summary Dashboard | Monthly | [AI Governance Lead] | This document (Section 3) | | Review KPIs in management review | Quarterly | [Management] | MANAGEMENT-REVIEW-TEMPLATE | | Reassess targets | Annually | [AI Governance Lead] | Updated targets in this document | @@ -180,7 +180,7 @@ Organizations may define additional KPIs. Use the following template: --- -*AI Governance KPIs template — DevTrail Framework* +*AI Governance KPIs template — StrayMark Framework* *Aligned with ISO/IEC 42001:2023 Clause 9* - + diff --git a/.devtrail/00-governance/AI-LIFECYCLE-TRACKER.md b/.straymark/00-governance/AI-LIFECYCLE-TRACKER.md similarity index 92% rename from .devtrail/00-governance/AI-LIFECYCLE-TRACKER.md rename to .straymark/00-governance/AI-LIFECYCLE-TRACKER.md index b5ff98f..88a5879 100644 --- a/.devtrail/00-governance/AI-LIFECYCLE-TRACKER.md +++ b/.straymark/00-governance/AI-LIFECYCLE-TRACKER.md @@ -15,7 +15,7 @@ | Acme Sentiment Classifier | Classifier (NLP) | Monitoring | 2.1.0 | [ML Team Lead] | [YYYY-MM-DD] | Medium | | [System name] | [LLM / Classifier / Recommender / Agent / Other] | [Phase] | [Version] | [Owner] | [Date] | [Low / Medium / High / Critical] | -> **DevTrail mapping**: Each system should have corresponding ETH, MCARD, and AILOG documents. Use `devtrail status` to verify documentation coverage. +> **StrayMark mapping**: Each system should have corresponding ETH, MCARD, and AILOG documents. Use `straymark status` to verify documentation coverage. --- @@ -35,7 +35,7 @@ - [ ] Stakeholders and affected parties identified - [ ] Regulatory requirements mapped (REQ) -| DevTrail Evidence | Document Type | +| StrayMark Evidence | Document Type | |-------------------|---------------| | Requirements specification | REQ | | Architecture decision | ADR, AIDEC | @@ -55,7 +55,7 @@ - [ ] Initial performance benchmarks recorded - [ ] Data privacy assessment completed (DPIA if applicable) -| DevTrail Evidence | Document Type | +| StrayMark Evidence | Document Type | |-------------------|---------------| | Data quality assessment | MCARD | | Bias evaluation | ETH | @@ -76,7 +76,7 @@ - [ ] Explainability assessment passed - [ ] Sign-off from designated reviewer -| DevTrail Evidence | Document Type | +| StrayMark Evidence | Document Type | |-------------------|---------------| | Test results | TES | | Security assessment | ETH (Security section) | @@ -96,7 +96,7 @@ - [ ] Incident response procedures defined - [ ] Deployment recorded (AILOG) -| DevTrail Evidence | Document Type | +| StrayMark Evidence | Document Type | |-------------------|---------------| | Deployment record | AILOG | | Monitoring setup | AILOG | @@ -116,12 +116,12 @@ - [ ] User feedback collection mechanism in place - [ ] Periodic risk reassessment scheduled -| DevTrail Evidence | Document Type | +| StrayMark Evidence | Document Type | |-------------------|---------------| | Performance logs | AILOG | | Incidents | INC | | Risk reassessment | ETH | -| Compliance checks | `devtrail compliance` | +| Compliance checks | `straymark compliance` | --- @@ -137,7 +137,7 @@ - [ ] Replacement system documented (if applicable) - [ ] Final status recorded in this tracker -| DevTrail Evidence | Document Type | +| StrayMark Evidence | Document Type | |-------------------|---------------| | Retirement decision | ADR | | Final status update | AILOG | @@ -201,7 +201,7 @@ ## 5. ISO 42001 Annex A.6 Control Summary -| Control | Description | Lifecycle Phase(s) | DevTrail Evidence | +| Control | Description | Lifecycle Phase(s) | StrayMark Evidence | |---------|-------------|--------------------|--------------------| | A.6.2.2 | AI system design and development | Design, Development | ADR, AIDEC, REQ | | A.6.2.3 | Training and testing of AI models | Training/Testing | MCARD, TES | @@ -216,7 +216,7 @@ --- -*AI System Lifecycle Tracker template — DevTrail Framework* +*AI System Lifecycle Tracker template — StrayMark Framework* *Aligned with ISO/IEC 42001:2023 Annex A.6* - + diff --git a/.devtrail/00-governance/AI-RISK-CATALOG.md b/.straymark/00-governance/AI-RISK-CATALOG.md similarity index 94% rename from .devtrail/00-governance/AI-RISK-CATALOG.md rename to .straymark/00-governance/AI-RISK-CATALOG.md index 006e7a5..7a9e542 100644 --- a/.devtrail/00-governance/AI-RISK-CATALOG.md +++ b/.straymark/00-governance/AI-RISK-CATALOG.md @@ -2,7 +2,7 @@ > **Aligned with**: NIST AI 600-1 and ISO/IEC 42001:2023 Annex C > -> This document provides a centralized risk registry for AI systems managed under DevTrail. It maps risk entries to the 12 NIST AI 600-1 risk categories and aligns with ISO 42001 Annex A.5 (Assessing Impacts of AI Systems) and ISO/IEC 23894 (AI Risk Management). +> This document provides a centralized risk registry for AI systems managed under StrayMark. It maps risk entries to the 12 NIST AI 600-1 risk categories and aligns with ISO 42001 Annex A.5 (Assessing Impacts of AI Systems) and ISO/IEC 23894 (AI Risk Management). > > **This is a template** — populate with risks specific to your organization's AI systems. @@ -17,7 +17,7 @@ This risk catalog serves as the single source of truth for AI-related risks acro - **Regulatory mapping** to NIST AI 600-1 categories and ISO 42001 controls - **Continuous monitoring** through regular review cycles -> **DevTrail mapping**: ETH documents assess individual risks at the change level. This catalog consolidates organizational risks per ISO 42001 Annex A.5. +> **StrayMark mapping**: ETH documents assess individual risks at the change level. This catalog consolidates organizational risks per ISO 42001 Annex A.5. --- @@ -46,12 +46,12 @@ This risk catalog serves as the single source of truth for AI-related risks acro ### 2.3 Risk Management Phases (ISO/IEC 23894) -| Phase | Description | ISO 23894 Reference | DevTrail Evidence | +| Phase | Description | ISO 23894 Reference | StrayMark Evidence | |-------|-------------|--------------------|--------------------| | Identification | Discover and describe AI risks | Clause 6.1 | ETH documents, this catalog | | Assessment | Evaluate likelihood, impact, and risk score | Clause 6.2 | Risk Score in this catalog | | Treatment | Select and implement controls to mitigate risks | Clause 6.3 | Current Controls column, ADR for decisions | -| Monitoring | Track residual risk and control effectiveness | Clause 6.4 | Review Date, `devtrail metrics` | +| Monitoring | Track residual risk and control effectiveness | Clause 6.4 | Review Date, `straymark metrics` | --- @@ -196,7 +196,7 @@ This risk catalog serves as the single source of truth for AI-related risks acro --- -*AI Risk Catalog template — DevTrail Framework* +*AI Risk Catalog template — StrayMark Framework* *Aligned with NIST AI 600-1 and ISO/IEC 42001:2023 Annex C* - + diff --git a/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md b/.straymark/00-governance/C4-DIAGRAM-GUIDE.md similarity index 94% rename from .devtrail/00-governance/C4-DIAGRAM-GUIDE.md rename to .straymark/00-governance/C4-DIAGRAM-GUIDE.md index 3345363..0e44b9f 100644 --- a/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md +++ b/.straymark/00-governance/C4-DIAGRAM-GUIDE.md @@ -1,8 +1,8 @@ # C4 Model Diagram Guide -> This guide explains how to use the C4 Model with Mermaid syntax in DevTrail documents, particularly in ADR (Architecture Decision Record) documents. +> This guide explains how to use the C4 Model with Mermaid syntax in StrayMark documents, particularly in ADR (Architecture Decision Record) documents. -**Languages**: English | [Español](i18n/es/C4-DIAGRAM-GUIDE.md) +**Languages**: English | [Español](i18n/es/C4-DIAGRAM-GUIDE.md) | [简体中文](i18n/zh-CN/C4-DIAGRAM-GUIDE.md) --- @@ -12,12 +12,12 @@ The C4 Model (Context, Containers, Components, Code) is a set of abstractions fo Each level zooms into the previous one: -| Level | Shows | When to Use in DevTrail | +| Level | Shows | When to Use in StrayMark | |-------|-------|------------------------| | **1. Context** | System + users + external systems | ADR for system-level decisions, REQ for high-level requirements | | **2. Container** | Applications, databases, services | ADR for service architecture, deployment decisions | | **3. Component** | Internal modules within a container | ADR for module-level decisions, AILOG for significant refactors | -| **4. Code** | Classes, interfaces, functions | Rarely needed in DevTrail — use only for critical design patterns | +| **4. Code** | Classes, interfaces, functions | Rarely needed in StrayMark — use only for critical design patterns | --- @@ -131,7 +131,7 @@ C4Component ## Level 4: Code -Shows classes, interfaces, and their relationships. **Rarely needed** in DevTrail — use only for critical design patterns that require documentation. +Shows classes, interfaces, and their relationships. **Rarely needed** in StrayMark — use only for critical design patterns that require documentation. For code-level diagrams, use standard Mermaid class diagrams instead of C4: @@ -199,7 +199,7 @@ Rel(api, db, "Reads/Writes", "SQL") --- -## Integration with DevTrail Documents +## Integration with StrayMark Documents ### In ADR Documents @@ -234,4 +234,4 @@ Use a Level 1 (Context) diagram to illustrate: --- -*DevTrail v4.1.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/00-governance/CAC-FILING-GUIDE.md b/.straymark/00-governance/CAC-FILING-GUIDE.md new file mode 100644 index 0000000..6a8ccc6 --- /dev/null +++ b/.straymark/00-governance/CAC-FILING-GUIDE.md @@ -0,0 +1,123 @@ +# CAC Algorithm Filing Guide — StrayMark + +> Practical guide for completing a CACFILE document and navigating the dual-filing process administered by the Cyberspace Administration of China (CAC). + +**Languages**: English | [Español](i18n/es/CAC-FILING-GUIDE.md) | [简体中文](i18n/zh-CN/CAC-FILING-GUIDE.md) + +--- + +## When CAC Filing is Required + +Filing is required for services with **public-opinion attributes** or **social-mobilization capabilities** under: + +- *Provisions on the Administration of Algorithmic Recommendations of Internet Information Services* (in force since 2022-03-01) +- *Provisions on the Administration of Deep Synthesis* (in force since 2023-01-10) +- *Interim Measures for the Management of Generative AI Services* (in force since 2023-08-15) + +Indicators that the rules apply: + +- The service generates, synthesizes, or disseminates content viewable by the public. +- The service uses ranking, recommendation, search, or content selection that influences user opinion. +- The service operates in news, social media, audio/video, live-streaming, or generative-AI domains. +- The service is provided to users in mainland China. + +If any of the above apply, set `cac_filing_required: true` on the MCARD and create a CACFILE. Validation rule **CROSS-007** enforces the link. + +--- + +## Single vs. Dual Filing + +Two regulatory tracks coexist: + +| Track | Authority | What | When | +|-------|-----------|------|------| +| **Algorithm Filing** | National CAC (after online submission) | Disclosure of algorithm mechanism, target audience, security responsibility report | All in-scope algorithms | +| **Generative AI Large Model Filing** | Provincial CAC → National CAC | Two-stage technical testing + algorithm disclosure | Generative AI services with public-opinion / social-mobilization attributes | + +Generative AI services typically need **dual filing**: provincial security assessment first, then national algorithm filing. Set `cac_filing_type: dual` in this case. + +--- + +## Required Documents and Information + +The CACFILE template captures the canonical inputs. The most commonly requested artifacts are: + +| Artifact | Where in CACFILE | Notes | +|----------|------------------|-------| +| Service overview | § Service Overview | Name, provider, application domain, target audience | +| Algorithm self-assessment report | § Self-Assessment | Risks + mitigations across content compliance, privacy, bias, IP, minor protection | +| Internal algorithm management policy | § Internal Algorithm Management Policy | Designated responsible person, complaint handling, logging | +| Algorithm Security Responsibility Report | § Algorithm Security Responsibility Report | Per Art. 24 of the Algorithm Recommendation Provisions | +| Training data description | § Training Data Description | Sources, volume, lawfulness, sensitive categories filtered | +| Blocked keywords list | § Blocked Keywords Strategy | Prevent generation of content subverting state power, inciting separatism, undermining national unity, etc. | +| Testing question set | § Testing Question Set | Red-team prompts + pass thresholds | +| Service agreements + complaint channels | (free-form, link from § Internal Algorithm Management Policy) | User-facing terms and SLA | + +--- + +## Filing Status Lifecycle + +| Status | Meaning | +|--------|---------| +| `pending` | CACFILE drafted but not yet submitted | +| `provincial_submitted` | Submitted to provincial CAC; awaiting decision | +| `provincial_approved` | Provincial decision favorable; can proceed to national submission (for dual filing) | +| `national_submitted` | Submitted to national CAC | +| `national_approved` | Filing number issued (`cac_filing_number` populated) | +| `rejected` | Filing rejected; document reasons in *Filing Trail* | +| `not_required` | Initial assessment concluded the service is out of scope | + +Validation rule **CAC-002** (compliance check) flags filings that have been `pending` for more than 90 days as a partial pass. **CROSS-006** requires `cac_filing_number` to be populated whenever status is any `*_approved` value. + +--- + +## Public Disclosure of the Filing Number + +Once `cac_filing_number` is issued, providers must surface it to end-users. Common patterns: +- Footer of the service homepage: "**算法备案号: 网信算备XXXXXXXXXXXX**". +- Settings / About page within the app. +- Terms of service. + +Document the disclosure surface in the *Filing Trail* section, last row. + +--- + +## Self-Assessment Risk Categories + +The self-assessment must address at least these areas (CACFILE § Self-Assessment): + +- **Content compliance**: prevention of illegal content (subversion, separatism, terrorism, obscenity, violence, ethnic hatred, etc.). +- **Personal information protection**: alignment with PIPL (cross-link to PIPIA). +- **Bias / unfair differentiated treatment**: covers price discrimination, ranking manipulation, demographic bias. +- **Intellectual property**: training data licensing, output similarity to copyrighted works. +- **Minor protection**: special handling of users under 18 — content filters, time limits, anti-addiction. + +For services using third-party foundation models, the self-assessment must include an evaluation of the upstream provider's filing status. + +--- + +## Linkage to Other StrayMark Documents + +A complete filing artifact set typically references: + +```yaml +# Inside CACFILE-2026-04-25-001 frontmatter +related: + - MCARD-2026-04-25-001 # the model being filed + - TC260RA-2026-04-25-001 # TC260 risk assessment + - PIPIA-2026-04-25-001 # if personal information is processed + - AILABEL-2026-04-25-001 # GB 45438 labeling plan + - SBOM-2026-04-25-001 # training data inventory (GB/T 45652 compliance) +``` + +This linkage is what `straymark compliance --standard china-cac` walks to verify. + +--- + +## Sources + +- [China's Algorithm Filing Regime — Lexology](https://www.lexology.com/library/detail.aspx?g=3c7273cf-8f85-4702-af70-6edf394ff1c3) +- [Interim Measures for the Management of Generative AI Services — Library of Congress](https://www.loc.gov/item/global-legal-monitor/2023-07-18/china-generative-ai-measures-finalized/) +- [346 generative AI services filed with CAC — SCIO](http://english.scio.gov.cn/pressroom/2025-04/09/content_117814020.html) + + diff --git a/.straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md b/.straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md new file mode 100644 index 0000000..6ba8280 --- /dev/null +++ b/.straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md @@ -0,0 +1,197 @@ +# Charter Chain Evolution — StrayMark + +> Two complementary patterns for keeping a multi-Charter module honest: refreshing SpecKit artifacts before a Charter is declared, and amending a closed Charter when audit findings arrive after `status: closed`. + +**Languages**: English | [Español](i18n/es/CHARTER-CHAIN-EVOLUTION.md) | [简体中文](i18n/zh-CN/CHARTER-CHAIN-EVOLUTION.md) + +--- + +## Status + +**v0 — proven in N=1 domain** (`StrangeDaysTech/sentinel` CHARTER-18, 2026-05-15, Issue #156). + +Both patterns are conventions documented here as canonical framework guidance. The CLI ships read-only and scaffolding helpers (`straymark charter refresh-suggest`, `straymark charter amend`); the patterns themselves are operator-driven. Either pattern may evolve once a second adopter validates them — until then, the N=1-domain caveat applies (Principle #12). + +--- + +## Why this document exists + +StrayMark's Charter pattern (`STRAYMARK.md` §15) assumes a single Charter is the bounded unit of work. That works for isolated Charters. It also works for the *first* Charter in a chain. But when a module accumulates many user-story Charters over months, two failure modes surface that the per-Charter pattern alone does not address: + +1. **Spec drift at the chain level** — the SpecKit artifacts (`plan.md`, `data-model.md`, `contracts/*`, `quickstart.md`, `research.md`) were authored against the framework version and reality of the module at chain start. After 3+ Charters, accumulated learnings (reusable patterns extracted, code gaps found, framework conventions evolved, operator decisions ratified) have drifted the spec away from the implementation. Going directly from Charter-N close into Charter-(N+1) declare causes systematic mid-flight scope expansions and emergent `R (new, not in Charter)` entries. +2. **Audit findings at the cycle level** — external audit cycles run post-close (auditors execute asynchronously after the close ceremony). Critical or High findings can arrive after the Charter has been marked `status: closed`. The framework's options are then: (a) open a new Charter for remediation (heavy — full declare + Tasks + ceremony for ~5 file edits), or (b) leave the findings in `review.md` and lose the "atomic with the Charter" property. + +Pattern 1 below addresses (1). Pattern 2 addresses (2). The two compose — a Charter that *received* Pattern 1 is more likely to *avoid* Pattern 2, because the refresh absorbs the pre-execution risk that the audit would surface post-close. They are complementary, not substitutable. + +--- + +## Pattern 1 — Pre-declare SpecKit refresh + +### When this pattern applies + +Adopt this pattern when **all** of these hold for a SpecKit-driven module: + +- The module has **3 or more closed Charters** (chain length ≥ 3). +- The rolling mean of `charter_telemetry.agent_quality.r_n_plus_one_emergent_count` across the last 3 closed Charters is **> 6**. +- No refresh PR has landed in the SpecKit artifacts since the chain's last branch point. + +Run `straymark charter refresh-suggest ` to evaluate the heuristic against your `.telemetry.yaml` history. The CLI reads the last closed Charters of the named module and prints a recommendation; it does not mutate anything. + +Below the threshold, the per-Charter pattern alone is sufficient — adopting the refresh too early adds a PR's worth of overhead without payoff. + +### Shape + +A **dedicated refresh PR** lands between Charter-N close and Charter-(N+1) declare. It touches only the **non-locked sections** of the SpecKit artifacts: + +- `specs//plan.md` — phase plans, dependency notes, sequencing. +- `specs//data-model.md` — entities, fields, conventions. +- `specs//contracts/*.md` — interface contracts, request/response shapes. +- `specs//quickstart.md` — runnable scenarios. +- `specs//research.md` — accumulated knowledge (see "Categorized learnings table" below). + +`research.md` carries the load-bearing artifact: a **categorized learnings table** consolidating what the chain learned. Minimum buckets: + +| Bucket | What goes here | +|---|---| +| Reusable patterns | Idioms / utilities / wrappers that emerged across Charters and should be inherited going forward (e.g. `withRLS` wrapper, brand-cache LRU, dedup table pattern). | +| Code gaps | Identified-but-unfixed work the chain discovered but did not close (e.g. unwired tables, stub implementations, missing columns). Each gap is a `Gn` entry with description + owning Charter (current or future). | +| Discipline patterns | Process learnings the chain ratified (e.g. cross-family audit pair, batch-complete discipline, per-batch close cadence). | +| Empirical corrections | Places where the spec drifted from the implementation. `EC1...ECn` entries: spec said X, reality is Y, reconciliation chosen. | + +Optional **operator decisions (Dn)** are ratified pre-declare with: decision, alternatives considered, chosen path, rationale. Subsequent Charters inherit Dn as contracts. + +### Mechanics + +1. **Refresh PR** before the next Charter declare. Optional AIDEC documenting the refresh decision + alternatives considered. The PR title should make the scope explicit (e.g. `spec(): US plan refresh — LOCKED-aware Phase 7+8 redesign`). +2. **Categorized learnings table** in `research.md` with the four buckets above. Each entry has a stable id (Pn / Gn / DPn / ECn) so subsequent Charters can cite by id. +3. **Operator decisions (Dn)** if applicable — listed explicitly with alternatives + chosen path + rationale. +4. **Next Charter's `## Context` section** cites each pattern, correction, and decision by id. Charter scope is grounded in refreshed reality, not in the chain-start spec. + +### Telemetry + +Populate `charter_telemetry.pre_declare_refresh:` in the *next* Charter's telemetry (the one that consumed the refresh, not the refresh PR itself): + +```yaml +pre_declare_refresh: + enabled: true + refresh_pr: "owner/repo#76" + refresh_aidec: "AIDEC-YYYY-MM-DD-NNN-speckit-refresh" + reusable_patterns_integrated: 7 + code_gaps_integrated: 4 + discipline_patterns_integrated: 3 + empirical_corrections_integrated: 15 + operator_decisions_ratified: 3 +``` + +Omit the block entirely if no refresh occurred — absence means "pattern not used". + +### Why this works (empirical) + +Sentinel CHARTER-18 was the first Charter in a 7-Charter chain to close cleanly without a mid-flight remediation Charter. `estimation_drift_factor: 1.0`, `pre_work.items_discovered_during_planning: 0`, `overall_satisfaction: 5/5`. Operator's drift reason statement: *"the SpecKit refresh from PR #76 ... eliminated most ambiguity that drove drift in prior Charters. No mid-flight remediation Charter required — the EC1..EC15 empirical-corrections inventory in research.md absorbed what would have been pre-execution risk into in-execution awareness."* + +--- + +## Pattern 2 — Post-close audit-driven amendment (Batch N.4) + +### When this pattern applies + +Adopt this pattern when **all** of these hold after a Charter has been marked `status: closed`: + +- One or more external audit findings emerge in the post-close `review.md` graded **Critical** or **High**. +- The Charter's `closure_criterion` is materially unmet by the un-remediated findings (i.e. shipping as-is would invalidate the close). +- The fix surface fits in **one cohesive PR** (~< 25 files, no architectural reopen — no new abstractions, no migrations, no API breaks). + +If the fix surface is larger or architectural, open a new Charter instead. The amendment pattern exists for the bounded case; it is not a Charter-evasion mechanism. + +### Shape + +The amendment rides **the same execute branch** as the original Charter (the branch is still mergeable to `main`; the amendment commit lands on top). A **new AILOG** documents the amendment — not an edit of the original AILOG. + +``` +charter--execute branch +├── (original commits — Charter execute work) +├── commit X: charter close (status: closed, telemetry.yaml written) +└── commit Y: charter-(batch-7.4): audit-driven remediation — + ↑ + AILOG-YYYY-MM-DD-MMM (NEW) documents this commit + AILOG-YYYY-MM-DD-NNN (ORIGINAL) gets a `## Historical correction` subsection + pointing forward to AILOG-...-MMM +``` + +### Mechanics + +1. **Same execute branch** — do not branch off `main`. The original Charter's execute branch is still the unit; the amendment commit rides along. +2. **New AILOG** under `.straymark/07-ai-audit/agent-logs/` documents the amendment. Convention: `risk_level: high` and `review_required: true`. The new AILOG carries an `amends:` field pointing back to the original AILOG id. +3. **Historical correction in the original AILOG** — append a `## Historical correction (YYYY-MM-DD)` subsection at the end of the original AILOG with the forward pointer to the new AILOG. Audit decisions are distinct from execute decisions; the original's body remains intact as the historical record. +4. **PR commentary** — if the execute PR has not yet merged, add the amendment commit to it and update the PR description with a "Batch N.4 amendment" subsection listing the closed findings. If the PR already merged, open a follow-up PR that references the original PR and the AILOG. +5. **Telemetry** — populate `charter_telemetry.post_close_amendment:` (see below). Use `straymark charter audit --merge-reports --merge-into ` to merge external audit findings into the same file; the CLI tolerates `external_audit: []` placeholder rewrites in v0.2+. + +`straymark charter amend ` scaffolds steps 2, 3, and 5 (creates the new AILOG stub, edits the original AILOG with the Historical correction subsection, prints the YAML block). It does not touch git — the operator decides when to commit. + +### Telemetry + +Populate `charter_telemetry.post_close_amendment:` in the Charter's `.telemetry.yaml`: + +```yaml +post_close_amendment: + applied: true + trigger: "external_audit" # external_audit | production_incident | deferred_implementation + ailog_id: "AILOG-YYYY-MM-DD-MMM" # the NEW AILOG, not the original + findings_closed: 5 + files_modified: 19 + effort_hours: 6.0 +``` + +Omit the block entirely if no amendment occurred. + +### Why this works (empirical) + +Sentinel CHARTER-18 closed 2026-05-15 with `external-audit-pending.yaml`. Audit reports landed 2026-05-15..05-17. Five findings (4 Critical/High from `gpt-5.3-codex`, 1 Critical from `gemini-2.5-pro`, 1 Medium found by the calibrator) were code-level fixes — DI wiring, retry header parsing, multi-tenant filter, timeout default. The Batch 7.4 amendment closed all five in one cohesive commit (19 files, +2257/-106 lines). A new Charter would have created multi-week governance overhead for ~6h of focused engineering. + +--- + +## Cross-pattern composition + +The two patterns operate at different levels of the chain and compose: + +| Pattern | Level | Frequency | Absorbs | +|---|---|---|---| +| Pre-declare SpecKit refresh | Chain / module | Once per 3+ Charters | Spec-level drift (architectural assumptions, table naming, framework version evolution) | +| Post-close audit-driven amendment | Cycle / Charter | Per Charter when triggered | Runtime-level drift (DI wiring, retry semantics, multi-tenant filters) | + +A Charter that *received* Pattern 1 is more likely to *avoid* Pattern 2 — the refresh absorbs pre-execution risk that would otherwise surface as post-close findings. But CHARTER-18 needed *both* — the refresh handled spec-level drift; the amendment handled runtime-level drift the refresh did not reach into. Encourage Pattern 1 at the chain level; tolerate Pattern 2 at the cycle level. + +--- + +## Authority / acceptance flow for upstreaming new patterns + +This document is itself the output of the acceptance flow Sentinel walked through for these two patterns (Issue [#156](https://github.com/StrangeDaysTech/straymark/issues/156)). The canonical flow for upstreaming a new Charter-chain pattern is: + +1. **Adopter-local RFC** lives at `.straymark/06-evolution/-rfc.md` in the adopter's own tree. The adopter ships the pattern there first — N=1 evidence is necessary but not sufficient. +2. **Upstream Issue** in `StrangeDaysTech/straymark` mirroring the local RFC body, with telemetry citations and PR links. +3. **Upstream acceptance** lands as: (a) a doc here in `00-governance/` describing the pattern canonically, (b) telemetry schema additions (opt-in), (c) optional CLI scaffolding for the operator-facing mechanics. The N=1-domain caveat carries forward to v1 stabilization. +4. **Second-domain validation** before the pattern's schema fields graduate from optional to recommended. + +`06-evolution/` is the canonical adopter-local home for in-flight RFCs. Once accepted upstream, the canonical home is `00-governance/.md` — the convention this document instantiates. + +--- + +## Open questions + +- **Threshold tuning** — the rolling-mean threshold of 6 for `r_n_plus_one_emergent_count` is Sentinel-derived. A second domain may move it. The `straymark charter refresh-suggest` CLI exposes `--threshold N` for adopter calibration. +- **Module heuristic** — `refresh-suggest ` currently matches `` against the Charter title and slug. SpecKit-conventional modules (`specs/-/`) could provide a stricter binding via the Charter's `originating_spec` field in a future fw bump. +- **Amendment frequency cap** — Pattern 2 is bounded by "one cohesive PR". A Charter receiving two or more amendment commits over time should be re-evaluated as a sign that the original close was premature. + +--- + +## Related + +- [EMERGENT-OBSERVATION-DESIGN.md](EMERGENT-OBSERVATION-DESIGN.md) — the meta-pattern of which Pattern 1 and Pattern 2 are applications (formal cross-referencing + cultural permission to surface). +- [STRAYMARK.md §15](../../STRAYMARK.md) — Charter lifecycle and the per-Charter pattern this document extends. +- [SPECKIT-CHARTER-BRIDGE.md](SPECKIT-CHARTER-BRIDGE.md) — how SpecKit artifacts map to Charters; Pattern 1 lives on this seam. +- [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) — sibling pattern for accumulated `§Follow-ups` across many AILOGs. +- [`.straymark/schemas/charter-telemetry.schema.v0.json`](../schemas/charter-telemetry.schema.v0.json) — `pre_declare_refresh` and `post_close_amendment` are defined here. + +--- + +*StrayMark fw-4.17.0 | [GitHub](https://github.com/StrangeDaysTech/straymark) | Issue [#156](https://github.com/StrangeDaysTech/straymark/issues/156)* diff --git a/.straymark/00-governance/CHINA-REGULATORY-FRAMEWORK.md b/.straymark/00-governance/CHINA-REGULATORY-FRAMEWORK.md new file mode 100644 index 0000000..771972e --- /dev/null +++ b/.straymark/00-governance/CHINA-REGULATORY-FRAMEWORK.md @@ -0,0 +1,92 @@ +# China Regulatory Framework — StrayMark + +> Overview of how StrayMark maps the six Chinese AI / data regulations covered when `regional_scope: china` is enabled in `.straymark/config.yml`. + +**Languages**: English | [Español](i18n/es/CHINA-REGULATORY-FRAMEWORK.md) | [简体中文](i18n/zh-CN/CHINA-REGULATORY-FRAMEWORK.md) + +--- + +## Activation + +Chinese regulatory checks are **opt-in**. Enable them in `.straymark/config.yml`: + +```yaml +regional_scope: + - global # NIST + ISO 42001 (always available) + - eu # EU AI Act + GDPR + - china # adds the 6 frameworks below +``` + +When `china` is in scope: +- `straymark new` exposes the four China-specific document types (PIPIA, CACFILE, TC260RA, AILABEL). +- `straymark compliance --all` includes the six Chinese checkers. +- `straymark validate` enforces CROSS-004…CROSS-011 and TYPE-003…TYPE-006. + +A project without `china` in scope is unaffected. + +--- + +## Coverage Matrix + +| # | Regulation | Type | Status | StrayMark Evidence | +|---|------------|------|--------|-------------------| +| 1 | **TC260 AI Safety Governance Framework v2.0** (15 Sep 2025) | Recommended (in drafting as GB) | Active | TC260RA template; `tc260_risk_level`, `tc260_application_scenario`, `tc260_intelligence_level`, `tc260_application_scale` fields on ETH / AILOG / MCARD / SEC | +| 2 | **PIPL** + **PIPIA** (Personal Information Protection Law, Art. 55-56) | Mandatory | Active since 2021-11-01 | PIPIA template; `pipl_*` fields cross-document; PIPIA retention ≥ 3 years | +| 3 | **GB 45438-2025** Cybersecurity Technology — Labeling Method for AI-Generated Content | **Mandatory** | In force 2025-09-01 | AILABEL template; `gb45438_*` fields on MCARD | +| 4 | **CAC Algorithm Filing** (Internet Information Service Algorithm Recommendation Provisions; Interim Measures for GenAI Services) | Mandatory for in-scope services | Active | CACFILE template; `cac_filing_required`, `cac_filing_number`, `cac_filing_status` fields on MCARD | +| 5 | **GB/T 45652-2025** Pre-training & fine-tuning data security | Recommended | In force 2025-11-01 | `gb45652_training_data_compliance` field on SBOM / MCARD; SBOM "GB/T 45652 Training Data Compliance" section | +| 6 | **CSL 2026** Cybersecurity Law amendments + Administrative Measures for National Cybersecurity Incident Reporting | Mandatory | In force 2026-01-01 | INC "CSL 2026 Incident Reporting" section; `csl_severity_level`, `csl_report_deadline_hours` fields on INC | + +--- + +## Document Type → Framework Mapping + +| Framework | Primary template | Cross-references | Optional fields elsewhere | +|-----------|-----------------|------------------|---------------------------| +| TC260 v2.0 | TC260RA | ETH, MCARD | `tc260_risk_level` on AILOG / SEC | +| PIPL / PIPIA | PIPIA | DPIA (cross-reference) | `pipl_applicable` on ETH / MCARD | +| GB 45438 | AILABEL | MCARD (generative models) | `gb45438_applicable` on MCARD | +| CAC Algorithm Filing | CACFILE | MCARD, SBOM | `cac_filing_number` on MCARD | +| GB/T 45652 | (Sections in SBOM and MCARD) | TC260RA | `gb45652_training_data_compliance` | +| CSL 2026 | INC (extended) | (none) | `csl_severity_level` on INC | + +--- + +## Implementation Guides + +| Framework | Guide | +|-----------|-------| +| TC260 v2.0 risk grading | [TC260-IMPLEMENTATION-GUIDE.md](TC260-IMPLEMENTATION-GUIDE.md) | +| PIPL Art. 55 trigger → PIPIA | [PIPL-PIPIA-GUIDE.md](PIPL-PIPIA-GUIDE.md) | +| Dual filing process | [CAC-FILING-GUIDE.md](CAC-FILING-GUIDE.md) | +| Explicit + implicit labeling | [GB-45438-LABELING-GUIDE.md](GB-45438-LABELING-GUIDE.md) | + +--- + +## Compliance Checks + +When `china` is in `regional_scope`, the following compliance checks are exposed via `straymark compliance --standard `: + +| `--standard` | Check IDs | Validates | +|--------------|-----------|-----------| +| `china-tc260` | TC260-001 / 002 / 003 | At least one TC260RA exists; high-risk levels require human review; the three grading criteria are populated | +| `china-pipl` | PIPL-001 / 002 / 003 / 004 | PIPIA exists when `pipl_applicable` or sensitive_data; cross-border transfer documented; retention ≥ 3 years | +| `china-gb45438` | GB45438-001 / 002 / 003 | AILABEL exists when an MCARD declares generative content; explicit + implicit labeling strategies declared; metadata fields populated | +| `china-cac` | CAC-001 / 002 / 003 | CACFILE exists when `cac_filing_required: true`; status not stuck in `pending` for > 90 days; filing number populated when status is `*_approved` | +| `china-gb45652` | GB45652-001 / 002 | SBOM declares per-row training data compliance; MCARD describes data security controls | +| `china-csl` | CSL-001 / 002 / 003 | INC has `csl_severity_level`; deadline hours coherent with severity (1h ↔ particularly_serious, 4h ↔ relatively_major); 30-day post-mortem documented for ≥ relatively_major | + +`straymark compliance --region china` runs all six. + +--- + +## Sources + +- [TC260 AI Safety Governance Framework v2.0 — Geopolitechs analysis](https://www.geopolitechs.org/p/china-releases-upgraded-ai-safety) +- [GB 45438-2025 — Code of China](https://www.codeofchina.com/standard/GB45438-2025.html) +- [Measures for the Identification of AI-Generated (Synthetic) Content (Regulations.AI)](https://regulations.ai/regulations/RAI-CN-NA-MIASCXX-2025) +- [China's PIPIA under PIPL — Securiti](https://securiti.ai/personal-information-protection-impact-assessment-pipia-under-china-pipl/) +- [China's Algorithm Filing Regime — Lexology](https://www.lexology.com/library/detail.aspx?g=3c7273cf-8f85-4702-af70-6edf394ff1c3) +- [China Cybersecurity Law amendments effective 2026-01-01 — Mayer Brown](https://www.mayerbrown.com/en/insights/publications/2025/12/china-finalises-amendments-to-the-cybersecurity-law-what-businesses-need-to-know-before-1-january-2026) + + diff --git a/.devtrail/00-governance/DOCUMENTATION-POLICY.md b/.straymark/00-governance/DOCUMENTATION-POLICY.md similarity index 52% rename from .devtrail/00-governance/DOCUMENTATION-POLICY.md rename to .straymark/00-governance/DOCUMENTATION-POLICY.md index 5686370..26536bf 100644 --- a/.devtrail/00-governance/DOCUMENTATION-POLICY.md +++ b/.straymark/00-governance/DOCUMENTATION-POLICY.md @@ -1,15 +1,20 @@ -# Documentation Policy - DevTrail +# Documentation Policy - StrayMark -## Governance Framework +**Languages**: English | [Español](i18n/es/DOCUMENTATION-POLICY.md) | [简体中文](i18n/zh-CN/DOCUMENTATION-POLICY.md) -This policy aligns DevTrail documentation with **ISO/IEC 42001:2023** (vertebral standard for AI Management Systems) and operationalizes: +## Why this policy exists +StrayMark externalizes the cognitive discipline of senior software engineering — explicit scope, declared decisions, named risks, recorded alternatives, audited trails — into versioned files alongside the code. This policy defines the document types, metadata, and governance rules that make that discipline auditable. + +As a side effect of producing those artifacts, the project accumulates evidence that maps cleanly onto the major AI governance frameworks: + +- **ISO/IEC 42001:2023** — vertebral standard for AI Management Systems - **EU AI Act** (effective August 2026) — risk classification, transparency, incident reporting - **NIST AI RMF 1.0 + AI 600-1** — AI risk management functions and generative AI profiles - **ISO/IEC 23894:2023** — AI risk management framework - **GDPR** — data protection and privacy impact assessments -All document types, metadata fields, and governance rules contribute to evidence that satisfies these regulatory frameworks. See Section 8 for the complete standards reference. +The policy is written for the engineering work first; compliance is what falls out when the work is documented with discipline. See Section 8 for the complete standards reference and the upstream repo's `Propuesta/straymark-design-principles.md` for the product-level rationale. --- @@ -93,6 +98,9 @@ related: | `observability_scope` | OTel instrumentation level: `none \| basic \| full` | When the change involves observability instrumentation | | `api_spec_path` | Path to OpenAPI/AsyncAPI specification file | In REQ documents when the requirement involves API interfaces | | `api_changes` | List of API endpoints affected | In ADR documents when the decision modifies public APIs | +| `reviewed_by` | Identity of the human reviewer (email, GitHub handle, or DID) | Set by the reviewer when formally approving a `review_required: true` document | +| `reviewed_at` | Date of the formal approval (`YYYY-MM-DD`, must be ≥ `created`) | Set with `reviewed_by` | +| `review_outcome` | Closure signal: `approved \| revisions_requested \| rejected` | Set with `reviewed_by`. Presence is the canonical "human has reviewed" signal — see §4.5 below | ### Tags Convention @@ -111,12 +119,12 @@ tags: [sqlite, persistence, hexagonal-architecture, repository-pattern] ### Related Convention -Related references link documents to other **DevTrail documents** within the same project. They enable cross-navigation in tools like `devtrail explore`. +Related references link documents to other **StrayMark documents** within the same project. They enable cross-navigation in tools like `straymark explore`. **Format rules:** - Use the **document filename** (with `.md` extension): `AILOG-2026-02-03-001-implement-sync-item.md` - For governance or non-typed documents, use the filename as-is: `AGENT-RULES.md`, `DOCUMENTATION-POLICY.md` -- Paths are resolved relative to `.devtrail/` — if the document is in a subdirectory, include the path from `.devtrail/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implement-sync-item.md` +- Paths are resolved relative to `.straymark/` — if the document is in a subdirectory, include the path from `.straymark/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implement-sync-item.md` - When the file is in the same directory as the referencing document, the filename alone is sufficient - **Do not use** external task IDs (`T001`, `US3`), issue numbers, or URLs — those belong in the document body, not in frontmatter - **Do not use** partial IDs without description (prefer `AILOG-2026-02-03-001-implement-sync-item.md` over `AILOG-2026-02-03-001`) @@ -128,32 +136,87 @@ related: - AIDEC-2026-02-02-001-sqlite-bundled-vs-system.md - AGENT-RULES.md -# Documents in specific subdirectories — include path from .devtrail/ +# Documents in specific subdirectories — include path from .straymark/ related: - 07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implement-sync-item.md - 02-design/decisions/ADR-2026-01-15-001-use-hexagonal-architecture.md ``` -**Resolution:** The CLI resolves references by searching: (1) exact ID match, (2) filename match anywhere in `.devtrail/`, (3) path suffix match. Using the full filename provides the most reliable resolution. +**Resolution:** The CLI resolves references by searching: (1) exact ID match, (2) filename match anywhere in `.straymark/`, (3) path suffix match. Using the full filename provides the most reliable resolution. --- ## 3. Document Statuses ``` -draft ──────► accepted ──────► deprecated - │ │ - │ ▼ - └──────► superseded +identified ──┐ + ├──► draft ──────► accepted ──────► deprecated + │ │ │ + │ │ ▼ + │ └──────► superseded + │ + └──► (TDE-only entry state, see §6) + │ + ▼ + resolved + (TDE-only terminal — debt paid; see §6) ``` | Status | Description | |--------|-------------| +| `identified` | Entry state for agent-driven discovery types (TDE today). Functionally equivalent to `draft` for lifecycle gating — a human reviewer is expected to prioritize and promote it. Semantically distinct so adopter analytics can distinguish "agent found this debt" from "human is drafting a deliberate doc". | | `draft` | In draft, pending review | | `accepted` | Approved and current | +| `resolved` | **TDE-only terminal state**: the technical debt described in this document has been addressed; the file is kept on disk as audit history. Distinct from `accepted` ("we accept this debt continues to exist"), `superseded` ("another TDE replaced this one"), and `deprecated` ("the TDE concept itself is no longer relevant"). The canonical closing reference (the Charter, PR, or commit that paid the debt) goes in the `## Resolution` body section. | | `deprecated` | Obsolete, but kept as reference | | `superseded` | Replaced by another document | +The per-type default status mapping lives in §6 — most types enter at `draft` or `accepted`, but TDE enters at `identified` per the agent-autonomy boundary (agent identifies, human prioritizes). TDE is the only type today with a custom terminal state (`resolved`); the validator accepts `resolved` globally as a stop-gap. A future per-doc-type lifecycle vocabulary (issue #149 Option B) will scope `resolved` to TDE strictly; until then, using it on non-TDE documents is allowed by the validator but semantically incorrect. + +--- + +## 3.5 Recording Approval + +`status` records the document's lifecycle state, and `review_required: true` records that *human review is needed*. Neither field records that human review *has actually happened*. This section defines the canonical closure signal for documents that need formal approval (AIDEC, ETH, MCARD, ADR, DPIA, INC, SEC and the China-scope variants — see AGENT-RULES.md §4 for the triggers). + +### Closure signal + +Three optional frontmatter fields, set by the reviewer at approval time: + +```yaml +reviewed_by: pepe@example.com # email | github-handle | DID +reviewed_at: 2026-05-02 +review_outcome: approved # approved | revisions_requested | rejected +``` + +Semantics: + +- **The presence of `review_outcome` is the closure signal.** A document with `review_required: true` and no `review_outcome` is *pending review*. +- `review_required: true` is **not** toggled to `false` after approval — it remains as historical record of why review was needed in the first place. +- `reviewed_at` must be `>= created`. If `reviewed_by` is set, `reviewed_at` and `review_outcome` must also be set (validated by `straymark validate`). +- `review_outcome: revisions_requested` allows iterative review cycles: the document is updated, and the reviewer eventually re-approves. The convention is to overwrite the three fields with the latest approval (frontmatter holds only the most recent state); the body section below preserves history. + +### Body section (canonical prose form) + +Add at the terminal position of the document body (e.g., before `## References` in AIDEC/ADR; after `## Review Schedule` in DPIA; after `## Post-Mortem Review` in INC). For templates that already include a `## Approval` table (ETH, MCARD, SEC, PIPIA, CACFILE, TC260RA, AILABEL), either form is canonical; the frontmatter fields are the machine-readable source of truth. + +```markdown +## Approval + +**Approved**: 2026-05-02 by `pepe@example.com`. + + +``` + +### Multi-reviewer flows (forward-looking) + +For documents that require multiple reviewers (e.g., ETH with both legal and engineering sign-off), the canon for v1 is to append additional `## Approval` blocks chronologically in the body, with the frontmatter reflecting the *latest* approval. A structured `review:` array form (one entry per reviewer) is forward-looking and not part of v1 — it will be added when at least one adopter exercises the multi-reviewer flow with real data. + +### CLI tooling + +`straymark approve --outcome approved --reviewer [--notes "..."] [--at YYYY-MM-DD]` writes both the frontmatter fields and the body section in one shot. `straymark validate --check-pending-reviews [--max-pending-days N]` lists `review_required: true` documents older than `N` days without a `review_outcome` (warn-only, no error). See CLI-REFERENCE.md. + --- ## 4. Risk Levels @@ -180,7 +243,7 @@ draft ──────► accepted ──────► deprecated ## 6. Folder Structure ``` -.devtrail/ +.straymark/ ├── 00-governance/ # Policies and rules ├── 01-requirements/ # System requirements ├── 02-design/ # Design and architecture @@ -211,7 +274,7 @@ draft ──────► accepted ──────► deprecated | `REQ` | Requirement | `01-requirements/` | `draft` | Yes | | `TES` | Test Plan | `04-testing/` | `draft` | Yes | | `INC` | Incident Post-mortem | `05-operations/incidents/` | `draft` | Yes | -| `TDE` | Technical Debt | `06-evolution/technical-debt/` | `identified` | No | +| `TDE` | Technical Debt | `06-evolution/technical-debt/` | `identified` (enters here; terminal `resolved` when debt paid — TDE-only) | No | | `SEC` | Security Assessment | `08-security/` | `draft` | Yes (always) | | `MCARD` | Model/System Card | `09-ai-models/` | `draft` | Yes (always) | | `SBOM` | Software Bill of Materials | `07-ai-audit/` | `accepted` | No | @@ -232,7 +295,7 @@ See also [ADR-2025-01-20-001] for architectural context. ## 8. Referenced Standards -| Standard | Version | Scope in DevTrail | +| Standard | Version | Scope in StrayMark | |----------|---------|-------------------| | ISO/IEC/IEEE 29148:2018 | 2018 | Requirements engineering — TEMPLATE-REQ.md | | ISO/IEC 25010:2023 | 2023 | Software quality model — TEMPLATE-REQ.md, TEMPLATE-ADR.md | @@ -244,7 +307,15 @@ See also [ADR-2025-01-20-001] for architectural context. | ISO/IEC 23894:2023 | 2023 | AI risk management — AI-RISK-CATALOG | | GDPR | 2016/679 | Data protection — ETH (Data Privacy), DPIA | | OpenTelemetry | Current | Observability — OBSERVABILITY-GUIDE, optional | +| TC260 AI Safety Governance Framework v2.0 *(China)* | Sept 2025 | AI risk grading — TEMPLATE-TC260RA.md (opt-in) | +| PIPL — Personal Information Protection Law *(China)* | 2021 | Data protection / PIPIA — TEMPLATE-PIPIA.md (opt-in) | +| GB 45438-2025 *(China, mandatory)* | Sept 2025 | AI-generated content labeling — TEMPLATE-AILABEL.md (opt-in) | +| CAC Algorithm Filing *(China)* | 2022+ | Algorithm registration — TEMPLATE-CACFILE.md (opt-in) | +| GB/T 45652-2025 *(China)* | Nov 2025 | Training-data security — TEMPLATE-SBOM.md, TEMPLATE-MCARD.md (opt-in) | +| CSL 2026 Cybersecurity Law *(China)* | Jan 2026 | Incident reporting — TEMPLATE-INC.md (opt-in) | + +> *Opt-in standards* are evaluated only when `regional_scope: china` is enabled in `.straymark/config.yml`. See `CHINA-REGULATORY-FRAMEWORK.md` for the full mapping. --- -*DevTrail v4.1.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/00-governance/EMERGENT-OBSERVATION-DESIGN.md b/.straymark/00-governance/EMERGENT-OBSERVATION-DESIGN.md new file mode 100644 index 0000000..de73fb0 --- /dev/null +++ b/.straymark/00-governance/EMERGENT-OBSERVATION-DESIGN.md @@ -0,0 +1,175 @@ +# Emergent Observation Design — StrayMark + +> Why agents reading StrayMark documentation surface what was not asked: the structural and cultural properties that make cross-source dissonance detectable, and the pyramid of applied patterns that already instantiate this meta. + +**Languages**: English | [Español](i18n/es/EMERGENT-OBSERVATION-DESIGN.md) | [简体中文](i18n/zh-CN/EMERGENT-OBSERVATION-DESIGN.md) + +--- + +## Status + +**v0 — proven in N=1 domain** (`StrangeDaysTech/sentinel`, Issue [#150](https://github.com/StrangeDaysTech/straymark/issues/150) → Issue [#156](https://github.com/StrangeDaysTech/straymark/issues/156), 2026-04-21 through 2026-05-15). + +This document names a *design property* of the StrayMark framework that produced an empirically observable emergent behaviour. The property is **not new** — it has been present since `00-governance/` was canonicalized — but it had not been *named*, which made it invisible to framework evolution and therefore at risk of accidental erosion. Naming it here protects it under the second-domain validation discipline of Principle #12. + +--- + +## Why this document exists + +An agent working in Sentinel surfaced — **without explicit trigger, without operator request, and without a CLI command designed to produce that output** — that `specs/002-commshub/plan.md` had accumulated twelve unreflected empirical learnings across seven consecutive Charters (CHARTER-07..17, ~1 month), and that filling CHARTER-18 against the stale spec carried ~50% probability of critical/high findings in the next audit cycle. That observation produced the upstream cycle that crystallized as `CHARTER-CHAIN-EVOLUTION.md` Pattern 1 in fw-4.16.0. + +The behaviour was reproduced because two properties of the documentation aparatus *coexisted consistently*. Neither alone would have sufficed. Naming both, and naming their composition, lets the framework's future evolution preserve them deliberately rather than by inheritance. + +The bridge `SPECKIT-CHARTER-BRIDGE.md` and the chain-evolution doc `CHARTER-CHAIN-EVOLUTION.md` document *one application* of this meta. This document names the meta itself and enumerates the other applications already shipped. + +--- + +## The two design properties + +### Property 1 — Structural cross-referencing (formal linkage) + +The framework does **not** delegate cross-document linkage to agent intuition or to prose. Every document type has *required* frontmatter fields and *canonical* sections that declare, in the document's own structure, which other documents it points to and which sections of itself are open to specific kinds of surfacing. + +Concrete instances that the agent encounters during routine reading: + +- **Frontmatter linkage fields** that resolve to other StrayMark documents: + - `originating_charter:` in AILOG / AIDEC frontmatter ([`AGENT-RULES.md` §5](AGENT-RULES.md), [`SPECKIT-CHARTER-BRIDGE.md` Charter↔AILOG section](SPECKIT-CHARTER-BRIDGE.md)) + - `originating_spec:` in Charter frontmatter ([`SPECKIT-CHARTER-BRIDGE.md`](SPECKIT-CHARTER-BRIDGE.md) §Frontmatter linkage) + - `originating_ailogs:` in Charter frontmatter (aggregation inverse) + - `amends:` in amendment AILOG frontmatter ([`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 2) + - `promoted_from_followup:` in TDE frontmatter ([`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md)) + - `related:`, `supersedes:`, `superseded_by:` ([`DOCUMENTATION-POLICY.md`](DOCUMENTATION-POLICY.md)) +- **Canonical sections inside templates** that hold deltas in queryable form: + - `§Risk: R (new, not in Charter)` in AILOGs ([`AGENT-RULES.md` §3](AGENT-RULES.md)) + - `## Follow-ups` per-AILOG ([`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md)) + - `## Batch Ledger` for multi-batch AILOGs + - `## Historical correction (YYYY-MM-DD)` appended to original AILOG on amendment ([`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md)) +- **Stable ID conventions** that make linkage cheap: + - `[TYPE]-[YYYY-MM-DD]-[NNN]-[description]` for date-bounded docs + - `CHARTER-NN-slug` (no timestamp, stable across renames) + - `FU-NNN` monotonic global, never renumbered +- **Bridge documents** that declare canonical relations between layers: + - `SPECKIT-CHARTER-BRIDGE.md` (Spec ↔ Charter ↔ AILOG) + - `CHARTER-CHAIN-EVOLUTION.md` (Charter ↔ Charter chain ↔ Spec refresh) +- **CLI commands** that cross sources mechanically: + - `straymark charter drift ` (declared scope ↔ commits) + - `straymark charter refresh-suggest ` (telemetry rolling-mean ↔ refresh need) + - `straymark validate` (frontmatter ↔ schema ↔ link integrity) + +**The point of Property 1**: when the agent encounters a divergence between two sources, the divergence is *structurally visible* — not buried in prose. The agent does not need to invent the connection; the connection is declared by the framework. + +### Property 2 — Cultural permission without gatekeeping + +The framework gives the agent explicit, repeated permission to surface beyond the asked task — and pairs that permission with autonomy to *act* on the surfacing (create the AILOG, file the TDE, open the AIDEC) without pre-approval. The operator retains prioritization, not creation. + +Concrete passages the agent encounters: + +- **`AGENT-RULES.md` §6 "Be Proactive"** — *"Identify potential risks, Suggest improvements when evident, Alert about technical debt"*. +- **`AGENT-RULES.md` §6 "Be Transparent"** — *"Explain the reasoning behind decisions, Document considered alternatives, Admit uncertainty when it exists"*. +- **`AGENT-RULES.md` §12 Audit Checkpoint** — *"the agent proactively offers an external multi-model audit"* — institutionalizes the *act* of surfacing as part of the workflow. +- **`PRINCIPLES.md` §2 "AI Agent Transparency"** — *"Not hide relevant information"*. +- **`AGENT-RULES.md` §3 "Create Freely" autonomy table** — AILOG, AIDEC, TDE creation requires no pre-approval; the agent files and the operator prioritizes. +- **`FOLLOW-UPS-BACKLOG-PATTERN.md` script auto-append** — `check-followups-drift.sh --apply` adds FU-NNN entries to the central registry without operator intervention. + +**The point of Property 2**: the agent has externalized *"should I say something?"* into *"is there a canonical section where this belongs?"*. If yes, surfacing is not a judgment call — it is execution of a documented rule. The cost of surfacing is low because the destination is pre-built. + +### Why the composition matters + +Property 1 *alone* — formal linkage without cultural permission — would produce a queryable corpus that no agent dares to query proactively. Property 2 *alone* — permission without structural cross-referencing — would produce vague surfacing ("I think something might be wrong somewhere") that operators cannot act on. + +Composed, they produce the observed behaviour: an agent reads the AILOGs, counts `R(new, not in Charter)` entries that materially diverge from the originating spec, sees that the spec has not been refreshed in a month, and — because `§6 Be Proactive` told it to alert and because the divergence has a name in the framework's vocabulary — surfaces *the specific, structurally-grounded delta* to the operator before proceeding with the asked task. + +This is the meta-pattern. + +--- + +## Empirical case: Sentinel spec-drift detection + +The case is described in detail in Issues [#150](https://github.com/StrangeDaysTech/straymark/issues/150) and [#156](https://github.com/StrangeDaysTech/straymark/issues/156), and codified as Pattern 1 in [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md). The compressed sequence: + +1. Sentinel runs `specs/002-commshub/plan.md` (committed 2026-04-21) through CHARTER-07..17 over ~1 month. Twelve empirical learnings accumulate across the AILOG chain in `§Risk: R(new, not in Charter)` sections and `## Follow-ups`. Pattern propagation (handler shapes, table-reuse conventions, RLS helper, etc.) crystallizes during execution. +2. CHARTER-18 is about to be declared. The agent — without instruction to do so — triangulates `plan.md` against the AILOGs (where `§Risk` entries name the spec gaps) and against the code (where `straymark charter drift` would have detected per-Charter divergence had it been run cross-Charter). The framework's `originating_spec:` linkage in each Charter, `originating_charter:` in each AILOG, and the `§Risk: R` convention make the triangulation mechanical, not heroic. +3. The agent surfaces *"if we fill CHARTER-18 reading the stale plan, the next audit cycle's H1/M1 findings will be remediating divergences atomically pre-close — ~50% probability of ≥1 critical/high finding from stale-premise inheritance"* — citing specific AILOGs by ID and specific code references. +4. The operator files Issue #150 as an RFC. The Sentinel-local AIDEC documents the proposed scope-limited refresh discipline + three mechanical gates. +5. Issue #156 upstreams the pattern. `CHARTER-CHAIN-EVOLUTION.md` Pattern 1 lands in fw-4.16.0 with telemetry slot `pre_declare_refresh:`, the helper `straymark charter refresh-suggest`, and the categorized learnings table contract. + +The observation is empirically reproducible: any spec that produces ≥3 Charters spaced ≥1 week apart will exhibit some degree of plan-vs-code drift, and an agent reading the framework's documentation has the structural and cultural permission to detect and surface it. + +--- + +## Pyramid of instances — applications of the meta-pattern + +The meta-pattern sits above several already-canonicalized patterns. Each is an *application* of the same underlying composition (formal linkage + cultural permission) to a specific source pair. + +| Application | Source pair | Where canonicalized | +|---|---|---| +| Pre-declare SpecKit refresh (Pattern 1) | spec ↔ AILOGs ↔ code | [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 1 | +| Post-close audit-driven amendment (Pattern 2) | audit findings ↔ closed Charter | [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 2 | +| Charter drift detection | declared scope ↔ commits | [`SPECKIT-CHARTER-BRIDGE.md`](SPECKIT-CHARTER-BRIDGE.md) + `straymark charter drift` | +| Follow-ups backlog drift | per-AILOG `§Follow-ups` ↔ central registry | [`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md) + `check-followups-drift.sh` | +| TDE-vs-`R` escalation | accumulated `§Risk: R` ↔ TDE backlog | [`AGENT-RULES.md`](AGENT-RULES.md) §3 | +| External audit checkpoint | implementation-complete state ↔ multi-model review | [`AGENT-RULES.md`](AGENT-RULES.md) §12 | + +These are not ad-hoc conventions. They share the same shape: *two canonical sources connected by frontmatter or section linkage, with the agent permitted (sometimes required) to surface the delta*. The next application axis — whatever it turns out to be — will recognize itself in this table. + +--- + +## Anti-patterns: how the meta is broken + +The meta-pattern is fragile. Each of the following, if introduced, regresses the framework's ability to produce emergent observations. + +- **Frontmatter linkage as optional**. If a new document type ships with `related:` / `originating_*` as advisory rather than required, the cross-referencing graph develops blind spots and the agent loses the ability to triangulate across that type. +- **Canonical sections collapsed into prose**. If `§Risk: R` is replaced by *"discussion of risks"*, the queryability evaporates. The agent can no longer count `R` entries to detect the saturation threshold that drives `refresh-suggest`. Free-form prose is not queryable; structured sections are. +- **Gatekeeping on agent-created docs**. Requiring pre-approval to file AILOG / AIDEC / TDE kills Property 2. The agent reverts to surfacing only what was asked, because the cost of surfacing rises above the local benefit. +- **Telemetry without emergent signals**. If `.telemetry.yaml` schemas evolve without preserving signals like `r_n_plus_one_emergent_count`, the operator loses visibility into how often the agent is surfacing emergent risks. The feedback loop breaks; the meta becomes invisible to framework evolution. +- **CLI commands that bypass the surface**. A CLI that emits decisions directly (no AILOG written, no `R` section populated) bypasses the structural surface. The agent's downstream triangulation degrades because the source pair is no longer connected via documents. + +--- + +## Open application axes — where the meta could replicate + +The audit underlying this document identified four loci where the structural infrastructure exists *partially* but the cultural permission or the application pattern has not been named. These are candidates for future application of the meta, not commitments to ship. + +- **MCARD ↔ deployed model code** — `TEMPLATE-MCARD.md` exists; no `model-version-at-close` field in Charter telemetry, no AILOG `deployed_mcard:` linkage field, no drift detection pattern. A model deployment that diverges from the MCARD on file is currently invisible. +- **SBOM ↔ lockfiles** — `AI-RISK-CATALOG.md` §RISK-004 mentions SBOM maintenance for AI components; no canonical AILOG field linking to SBOM, no drift script (analogous to `check-followups-drift.sh`) that compares declared SBOM against actual `package.lock` / `requirements.txt`, no telemetry signal for dependency-change events. +- **ADR vigente ↔ contradicting implementation** — `.telemetry.yaml` schema captures `decisions_contradicting_prior_adrs` but no protocol tells the agent *when* to surface a contradiction it observes during implementation. The signal exists; the surfacing convention does not. +- **Constitution Check ↔ framework version bump** — `SPECKIT-CHARTER-BRIDGE.md §Constitution Check re-evaluation cadence` codifies the cadence verbally; no automatic alert fires on `straymark update-framework`. A framework bump between Charters can change Constitution gates silently. + +These four are tracked in a single upstream RFC issue (filed after this document lands). Each requires empirical N=1 adopter validation before crystallizing as a named pattern — Principle #12 applies. + +--- + +## Authority / acceptance flow for naming new meta-applications + +The same upstream-acceptance flow that `CHARTER-CHAIN-EVOLUTION.md` documents applies recursively to this meta. A new application axis (one of the four above, or a fifth that emerges) lands as: + +1. **Adopter-local RFC** at `.straymark/06-evolution/-rfc.md` describing the structural connection that already exists (or is being added) and the cultural permission rule the agent should follow. +2. **Upstream Issue** mirroring the RFC, citing the AILOGs/Charters/telemetry where the empirical observation occurred. +3. **Upstream acceptance** as: (a) update to the relevant template / schema / governance doc to add the missing structural piece (frontmatter field, canonical section, telemetry signal); (b) addition of the axis to the "Pyramid of instances" table in this document; (c) optional CLI scaffolding for mechanical detection. +4. **Second-domain validation** before the axis's schema additions graduate from optional to recommended. + +This document itself instantiates step 3.b for the meta — the upstream-acceptance output of recognizing that the existing applications share a single underlying property. + +--- + +## Open questions + +- **Operationalizing "material divergence"**. The Principle #8 wording ([`PRINCIPLES.md`](PRINCIPLES.md)) leaves "material" to agent judgement. Per-application thresholds (Pattern 1 uses `r_n_plus_one_emergent_count > 6` rolling mean) are calibrated empirically. Whether a cross-axis threshold is achievable, or whether each axis must calibrate its own, is open. +- **Telemetry consolidation**. Each application currently emits its own telemetry slot (`pre_declare_refresh:`, `post_close_amendment:`, `r_n_plus_one_emergent_count`). A consolidated *"emergent observations surfaced this Charter"* counter might make the meta visible at the metrics level. Deferred — premature aggregation risks losing per-axis signal granularity. +- **Adopter onboarding**. New adopters reading `STRAYMARK.md` for the first time should encounter the meta early enough that they recognize the pattern when they experience it. Whether that lives in `QUICK-REFERENCE.md`, in `STRAYMARK.md` itself, or in a new onboarding section is open. + +--- + +## Related + +- [`PRINCIPLES.md`](PRINCIPLES.md) §8 — *Cross-Source Dissonance Surfacing* (the cultural rule, condensed). +- [`AGENT-RULES.md`](AGENT-RULES.md) §6 — *Be Proactive* (the operative mandate); §3 — *TDE vs `R`* (one application surface); §12 — *Audit Checkpoint* (institutionalized surfacing). +- [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) — Pattern 1, Pattern 2 (the two highest-level applications). +- [`SPECKIT-CHARTER-BRIDGE.md`](SPECKIT-CHARTER-BRIDGE.md) — Charter as the bridge layer where Property 1's linkage is densest. +- [`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md) — drift detection at the per-AILOG ↔ registry surface. +- [`DOCUMENTATION-POLICY.md`](DOCUMENTATION-POLICY.md) — frontmatter and `related:` field canon. +- [`../../STRAYMARK.md`](../../STRAYMARK.md) §15 — Charter as the bounded unit where applications converge. + +--- + +*StrayMark fw-4.17.0 | [GitHub](https://github.com/StrangeDaysTech/straymark) | Issue [#150](https://github.com/StrangeDaysTech/straymark/issues/150) · [#156](https://github.com/StrangeDaysTech/straymark/issues/156)* diff --git a/.straymark/00-governance/FOLLOW-UPS-BACKLOG-PATTERN.md b/.straymark/00-governance/FOLLOW-UPS-BACKLOG-PATTERN.md new file mode 100644 index 0000000..5fe9094 --- /dev/null +++ b/.straymark/00-governance/FOLLOW-UPS-BACKLOG-PATTERN.md @@ -0,0 +1,244 @@ +# Follow-ups Backlog Pattern - StrayMark + +> Reproducible convention for managing accumulated `§Follow-ups` and `R (new, not in Charter)` entries across many AILOGs and Charters. + +**Languages**: English | [Español](i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md) | [简体中文](i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md) + +--- + +## Status + +**v0 — proven in N=1 domain** (`StrangeDaysTech/sentinel` CHARTER-12, 2026-05-06). + +This is a **convention**, not a CLI feature. Adopters reproduce it locally with markdown + a portable bash script. The pattern may evolve into a `straymark followups` subcommand once a second adopter validates it (see [Open questions](#open-questions)). + +--- + +## When this pattern applies + +StrayMark's per-AILOG `§Follow-ups` convention works at write time — when an AILOG is created, the implementer documents what is deferred to subsequent Charters or operational triggers. That works fine until the cumulative list grows past what an operator can scan from memory. + +Adopt this pattern when **any** of these conditions hold: + +- The project has accumulated **~20 or more AILOGs** with non-trivial `§Follow-ups` sections. +- Operators repeatedly ask agents to "list what's pending across the project" and the answer requires a multi-file scan. +- A "do this when X arrives" follow-up was almost lost because the originating AILOG was never re-read after X arrived. +- A Charter retrospective surfaces follow-ups that should have been classified as `closed` weeks earlier but were never indexed. + +Below that volume, the per-AILOG convention alone is sufficient — adopting this pattern early adds maintenance overhead without payoff. + +--- + +## Shape + +### Registry file + +Single markdown file at the canonical path: + +``` +.straymark/follow-ups-backlog.md +``` + +### Frontmatter (YAML) + +```yaml +--- +last_scan: 2026-05-06 +last_scan_range: AILOG-NNNN-NN-NN-NNN..AILOG-NNNN-NN-NN-NNN # optional — first..last AILOG covered +schema_version: v0 +total_open: 0 # count of entries currently `open` +total_promoted: 0 # count of entries currently `promoted` (added in schema v0.1 — see "Promotion to TDE") +total_closed_in_session: 0 # count of `closed` entries since last session (optional, operator-maintained) +total_phase_blocked: 0 # count of `phase-blocked` entries (optional) +buckets: + - ready + - time-triggered + - charter-triggered + - phase-blocked + - operational +fully_extracted_ailogs: + - AILOG-2026-04-11-001 + - AILOG-2026-04-12-001 + # ... one entry per AILOG whose follow-ups have been processed +--- +``` + +The `total_*` counters are **operator-maintained metadata**. The drift script doesn't update them automatically — they live in the header so a session-start glance shows the registry's pulse without scrolling through buckets. `total_promoted` was canonicalized in schema v0.1 (Sentinel adopter empirical signal, fw-4.13.1) to mirror the existing `total_open` / `total_closed_in_session` / `total_phase_blocked` pattern. + +The `fully_extracted_ailogs` list is the **load-bearing metadata** for drift detection. Every AILOG whose `§Follow-ups` and `R` entries have been transferred into the registry (or explicitly classified as superseded) belongs in this list. Drift detection compares this list against AILOGs that have follow-up content in the repo. + +### Buckets + +Five buckets organize entries by trigger type: + +- `ready` — actionable now, no dependency on external trigger. +- `time-triggered` — calendar-based trigger (audit cycle, periodic review). +- `charter-triggered` — gated on a future Charter that touches the relevant area. +- `phase-blocked` — gated on a future component or phase that does not yet exist. +- `operational` — manual operator decision or external system action. + +### Entry schema + +Each entry inside a bucket follows this shape: + +```markdown +### FU-NNN — +- **Origin**: AILOG-NNNN-NN-NN-NNN +- **Status**: open | in-progress | closed | superseded | promoted +- **Trigger**: ready | | when | +- **Destination**: +- **Cost**: +- **Notes**: +- **Promoted to**: +``` + +`FU-NNN` is monotonically increasing across the registry's lifetime; do not renumber when entries close. + +### Status vocabulary + +- `open` — pending, not yet acted on. +- `in-progress` — a Charter has been declared or is executing that addresses this entry. +- `closed` — entry resolved (Charter merged, operational task done, time elapsed and reviewed). +- `superseded` — addressed by other work that did not reference this entry directly. +- `promoted` — the entry was elevated to a TDE document because it met the transversal-debt criteria (see "Promotion to TDE" below). The `Promoted to:` field carries the TDE id. + +Closed, superseded, and promoted entries stay in the file (auditable history). Operators may move them to a `## Bucket: closed` section at the bottom for visual decluttering, but they are never deleted. + +--- + +## Promotion to TDE + +Some FU entries are not just deferred tasks — they describe **transversal technical debt** that warrants its own governance document (TDE). The criteria for promotion mirror the TDE-vs-`R` disambiguation in `AGENT-RULES.md §3`: + +- The entry is *heritage from a prior Charter* (already lived through ≥1 Charter close without remediation). +- The entry *applies to multiple modules or multiple Charters* — the central registry has fragmented it into bullets that share a root cause. +- The entry *requires a dedicated Charter outside the current scope envelope* to remediate. +- The entry *requires human prioritization or assignment* that the periodic operator review cannot decide from the bullet alone (impact × effort matrix, ownership). + +When any of these holds, promote the FU entry to a TDE document under `.straymark/06-evolution/technical-debt/`: + +1. Create the TDE via `/straymark-new tde` (or `straymark new --type tde`). Fill `impact`, `effort`, `type`, and the body sections from the FU entry's context. +2. Add `promoted_from_followup: FU-NNN` to the TDE frontmatter for traceability. +3. In the FU entry, set `Status: promoted`, set `Destination: TDE-YYYY-MM-DD-NNN`, and add `Promoted to: TDE-YYYY-MM-DD-NNN`. Move the entry to the `## Bucket: closed` section if you maintain one; otherwise leave it in place with the new status. + +The FU entry is **not deleted** after promotion — its presence in the registry is the audit trail showing where the TDE came from. + +### Two promotion shapes — promotion-of-existing vs retroactive-at-creation + +The workflow above covers the **standard case**: an `open` FU entry already exists in the registry and gets elevated to a TDE during periodic review. There is a second case that is equally valid and that emerged empirically from the Sentinel CHARTER-13 retrospective: + +- **Promotion of existing entry** — an FU was registered (typically via `--apply`) as `open` weeks or Charters ago, lived through ≥1 Charter close without resolution, and meets the four criteria above. Standard flow. +- **Retroactive promotion at creation** — the debt is recognized as TDE-worthy *during* a retrospective (Charter close ceremony, audit cycle, RFC writeup) and never existed as an `open` FU. The TDE is created first; an FU entry is added to the registry *with `Status: promoted`* from birth, providing the audit trail back from the TDE to the originating context (an `R` in an AILOG, a calibrator finding, a deferred classification). + +Both shapes produce the same end state in the registry: an entry with `Status: promoted` and a `Promoted to: TDE-YYYY-MM-DD-NNN` pointer. The difference is whether the entry pre-existed as `open` or was born `promoted`. The drift script treats them identically (it doesn't differentiate by birth status), and adopter analytics counting `total_promoted` get the same number either way. + +When in doubt, prefer creating the FU entry — even retroactively — because it cross-references the TDE back to the AILOG / R-number / source context that triggered the recognition. A TDE with `promoted_from_followup: FU-NNN` pointing to an entry that exists in the backlog is more navigable than one pointing to a fictional FU. + +### When to promote + +- **Periodic review** — when the operator does the manual reclassification pass, promote any entry that has lived through ≥2 Charter closes without resolution and meets the criteria above. +- **Charter close** — when reviewing entries the just-closed Charter resolved, if you find entries that were *not* resolved and meet the criteria above, promote them rather than leaving them as `open`. +- **Pre-Charter declaration** — if you're about to declare a Charter and notice the registry contains entries that this Charter would *partially* address, the un-addressed portion may belong as a TDE rather than as another deferred FU. + +The drift script (`scripts/check-followups-drift.sh`) is **not extended** for promotion candidates in v0 — promotion is operator-driven. A future v1 enhancement could flag entries meeting the "lived through ≥2 Charters" heuristic, but that crystallizes after a second adopter validates the pattern (same gate as the rest of v0 → v1). + +--- + +## Drift detection + +A small bash script is the verification layer that keeps the registry in sync with new AILOGs. The script lives in the adopter's repo (suggested path: `scripts/check-followups-drift.sh`) and has three modes. + +### Modes + +- **Default** — scan AILOGs modified in `git diff origin/main..HEAD` (with `HEAD~1..HEAD` fallback). Warn on any AILOG with `§Follow-ups` / `R (new)` content that is not in `fully_extracted_ailogs`. Exit 1 on drift. +- **`--apply`** — same scan, but auto-append new entries under `## Bucket: ready` with auto-generated `FU-NNN` ids and append the AILOG id to `fully_extracted_ailogs`. The operator reclassifies into the correct bucket later. +- **`--scan-all`** — scan every AILOG in the project (periodic full sweep). + +### Per-AILOG vs per-bullet granularity + +Tracking is **per-AILOG**, not per-bullet. An AILOG is either fully extracted (its id is in `fully_extracted_ailogs` — trust the registry) or it is not (extract everything). Per-bullet matching would require fingerprinting (text hashing or fuzzy comparison), which produces false positives whenever a registry entry paraphrases the AILOG bullet — and curated entries always paraphrase. + +The cost of per-AILOG granularity: when a follow-up is added to an already-extracted AILOG post-Charter close, drift detection misses it. The remediation is operator-driven — manually remove the AILOG from `fully_extracted_ailogs` and re-run with `--apply`. This trade-off is intentional for v0 because most AILOGs are write-once after Charter close. + +### Script template + +A reference implementation (~290 lines of POSIX bash) is in `StrangeDaysTech/sentinel` at `scripts/check-followups-drift.sh`. Copy it into your repo and adjust the constants at the top: + +```bash +BACKLOG_FILE=".straymark/follow-ups-backlog.md" +AILOG_DIR=".straymark/07-ai-audit/agent-logs" +``` + +The script uses `awk` and `grep` only — no jq, no yq, no heavyweight dependencies. Portable across Linux and macOS. + +--- + +## Agent integration + +The agent (Claude / Gemini / etc.) becomes the primary maintainer of the registry. Add to your `CLAUDE.md` / `AGENT.md`: + +```markdown +## Follow-ups backlog + +- **Session start**: glance at `.straymark/follow-ups-backlog.md` to know what is pending across the project. +- **Pre-commit checklist**: created or modified any AILOG with `## Follow-ups` or `R (new, not in Charter)` entries? → run `scripts/check-followups-drift.sh --apply` to extend the backlog in the same commit. +- **Post-Charter close**: review entries the Charter resolved; mark them `closed` (with the closing Charter id in `Notes`) or `superseded`. For un-resolved entries that meet the TDE criteria (heritage from prior Charter, transversal, requires dedicated Charter, needs human prioritization), promote them to a TDE document (see "Promotion to TDE" in this pattern + `AGENT-RULES.md §3`). +``` + +This makes the agent the maintainer, the script the verification layer, and the operator the periodic reviewer (re-bucketing, marking closed, pruning superseded, promoting to TDE when criteria apply). + +--- + +## Adoption walkthrough + +For an adopter starting fresh: + +1. Create `.straymark/follow-ups-backlog.md` with the frontmatter above (empty `fully_extracted_ailogs:` list initially) and the five `## Bucket: ` headers. +2. Copy the reference script from `StrangeDaysTech/sentinel` to `scripts/check-followups-drift.sh`. Adjust `AILOG_DIR` if your AILOGs live elsewhere. +3. Run `scripts/check-followups-drift.sh --scan-all --apply` to seed the registry from existing AILOGs. +4. Reclassify the auto-generated `## Bucket: ready` entries into the correct buckets manually. This is one-time triage, typically 30-60 min for a backlog of ~50 entries. +5. Add the agent integration block to `CLAUDE.md` / `AGENT.md`. +6. Optionally wire `scripts/check-followups-drift.sh` into a pre-commit hook for hard enforcement. + +For an adopter migrating from ad-hoc tracking: the same flow, but step 4 may require deciding which entries are already `closed` or `superseded` — that classification is what makes the registry useful. + +--- + +## Reference implementation + +`StrangeDaysTech/sentinel` CHARTER-12, merged 2026-05-06: + +- Implementation PR: [sentinel#53](https://github.com/StrangeDaysTech/sentinel/pull/53) (registry + script + CLAUDE.md additions). +- Close-out PR: [sentinel#54](https://github.com/StrangeDaysTech/sentinel/pull/54) (post-merge verification + Charter close). + +Empirical context: 47 entries seeded from CHARTER-08 → CHARTER-11 retrospective (~30 min of multi-agent triage). The chain demonstrated the gap that motivated the pattern — without the registry, the operator could not see "what is pending across the project" without re-classifying each Charter's follow-ups in isolation. With the registry, session-start glance is one file read. + +--- + +## Open questions + +These are not resolved in v0. Future revisions of this pattern, or a CLI helper, may address them: + +- **Bucket classification heuristic**. Today `--apply` dumps every new entry into `## Bucket: ready`; the operator reclassifies manually. A heuristic using AILOG `tags` and Charter `effort_estimate` could suggest a bucket automatically. +- **Schema validation**. The registry follows a tacit schema; no `.straymark/schemas/follow-ups-backlog.schema.v0.json` exists yet. Validation today is human review. +- **Integration with the audit cycle**. When `straymark charter audit --merge-reports` produces real-debt findings that are not remediated atomically pre-close, those findings live only in `.straymark/audits//review.md`. They do not auto-flow into the central registry. Surfacing them automatically would close a known gap. +- **`closed` vs `superseded` semantics**. Today the difference is whether the resolving work explicitly referenced the entry. A stricter convention may emerge. +- **Cristalization as `straymark followups` CLI**. Once a second adopter validates the pattern, the framework may ship a subcommand mirroring the existing `straymark charter` trio: `list` / `close` / `drift`. Adopters at v0 (this pattern) migrate by deleting their local script and switching the agent instruction. + +--- + +## Credits + +Contributed via [issue #111](https://github.com/StrangeDaysTech/straymark/issues/111) by the Sentinel adopter. Empirical foundation: CHARTER-08 → CHARTER-11 chain in `StrangeDaysTech/sentinel`. Author: Claude Opus 4.7 on behalf of operator José Villaseñor Montfort. + +--- + +## Related + +- [EMERGENT-OBSERVATION-DESIGN.md](EMERGENT-OBSERVATION-DESIGN.md) — the meta-pattern that this drift-detection convention instantiates at the per-AILOG ↔ registry surface. +- [CHARTER-CHAIN-EVOLUTION.md](CHARTER-CHAIN-EVOLUTION.md) — sibling pattern that operates at chain level (Pattern 1) and cycle level (Pattern 2). +- [AGENT-RULES.md §3](AGENT-RULES.md) — TDE-vs-`R` escalation criteria that may promote follow-ups to dedicated debt entries. + +--- + +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/00-governance/GB-45438-LABELING-GUIDE.md b/.straymark/00-governance/GB-45438-LABELING-GUIDE.md new file mode 100644 index 0000000..254eba0 --- /dev/null +++ b/.straymark/00-governance/GB-45438-LABELING-GUIDE.md @@ -0,0 +1,127 @@ +# GB 45438 Content Labeling Guide — StrayMark + +> Practical guide for completing an AILABEL document under **GB 45438-2025** *Cybersecurity Technology — Labeling Method for Content Generated by Artificial Intelligence* and the CAC *Measures for the Identification of AI-Generated (Synthetic) Content*. + +**Languages**: English | [Español](i18n/es/GB-45438-LABELING-GUIDE.md) | [简体中文](i18n/zh-CN/GB-45438-LABELING-GUIDE.md) + +--- + +## Status + +GB 45438-2025 is a **mandatory** national technical standard, in force since **2025-09-01**. The CAC measures are the operational regulation that gives the standard teeth: any in-scope service must implement both **explicit** (visible) and **implicit** (machine-readable) labeling. + +A service is in scope when it generates, synthesizes, or substantially modifies any of these content types: + +- Text (chat completion, summarization, translation) +- Images (text-to-image, edit, face-swap, pose manipulation) +- Audio (voice cloning, TTS, music generation) +- Video (text-to-video, image-to-video, deep synthesis) +- Virtual scenes (immersive / hyperrealistic environments) + +If any apply, set `gb45438_applicable: true` on the MCARD and create an AILABEL. Validation rule **CROSS-010** enforces the link. + +--- + +## Two-Track Labeling + +### Explicit Labels (Visible) + +Must be perceivable by an ordinary user. Form depends on the medium: + +| Medium | Acceptable forms | +|--------|------------------| +| Text | Disclaimer line, banner, inline tag at start or end of message | +| Image | Visible watermark (corner badge, opacity overlay), caption | +| Audio | Audio cue at the start of the clip, periodic spoken disclosure for long clips | +| Video | Persistent watermark + disclosure on the first frame | +| Virtual scene | Persistent HUD banner or pre-entry notice | + +The explicit label should remain **prominent** and **legible** under reasonable viewing conditions. + +### Implicit Labels (Machine-Readable) + +Embed metadata in file headers. The standard mandates **at minimum**: + +- `content_type` — one of `text` / `image` / `audio` / `video` / `virtual_scene` +- `service_provider_code` — issued by CAC after filing (link to CACFILE) +- `content_id` — unique identifier per artifact (UUIDv7 / ULID recommended) + +StrayMark's AILABEL template captures these fields under section 3.2. + +GB 45438 **encourages** (does not mandate) digital watermarks for additional persistence — see § 3.3 of the AILABEL. + +--- + +## Choosing a Metadata Format + +| Format | Pros | Cons | +|--------|------|------| +| **C2PA** (Content Credentials) | Industry standard, signed, broad ecosystem support | Heavier; requires PKI | +| **XMP** | Mature in image/video tooling | Often stripped by social platforms | +| **EXIF** | Universal in image tooling | Limited to images; trivially stripped | +| **Custom** | Tailored fields | Requires distributor cooperation for verification | +| **None** | — | Non-compliant with GB 45438 | + +For text-only services, you can encode the implicit metadata as Unicode private-use characters or a JSON envelope around the response. Document the choice in section 3.1. + +--- + +## Persistence Requirements + +GB 45438 expects implicit labels to persist when files are downloaded, exported, or copied. Provide evidence in section 4 of the AILABEL: + +| Operation | Test | +|-----------|------| +| Direct download | Re-read the metadata from the downloaded file | +| Re-export from a different tool | Open in a third-party editor, save, re-read | +| Screenshot / screen capture | Watermark survives even though metadata is stripped | +| Re-encoding | Robust watermark survives JPEG/MPEG re-encoding | + +If the explicit label cannot survive (e.g., a screenshot of plain text), the **implicit** label or a **robust visible watermark** must. + +--- + +## Distributor Obligations + +Platforms that distribute AI-generated content must: +- Verify metadata when present. +- Surface a prominent prompt to viewers when synthetic content is identified. +- Refrain from removing or altering existing labels. + +If your service distributes content from upstream providers, document in section 5 of the AILABEL how you implement these obligations. Set `gb45438_distributor_obligations_documented: true` once complete. + +--- + +## Linkage with Other Frameworks + +GB 45438 does not stand alone. It interacts with: + +| Framework | Interaction | +|-----------|-------------| +| **CAC Algorithm Filing** | The `service_provider_code` in the implicit metadata is **issued by CAC** after a successful filing. The AILABEL must reference the CACFILE. | +| **EU AI Act Art. 50** | EU has a parallel transparency obligation. A single labeling design can satisfy both, but languages and verification surfaces may differ. | +| **TC260 v2.0** | Labeling-failure should appear as an `application_risk` in the TC260RA when `gb45438_applicable: true`. | +| **C2PA / W3C Provenance Working Group** | Industry-driven standards converging with GB 45438. Choosing C2PA aligns global and Chinese requirements. | + +--- + +## Compliance Checks + +`straymark compliance --standard china-gb45438` evaluates: + +| Check | Validates | +|-------|-----------| +| GB45438-001 | An AILABEL exists for every MCARD with `gb45438_applicable: true` | +| GB45438-002 | Both `gb45438_explicit_label_strategy` **and** `gb45438_implicit_metadata_format` are populated (cannot pick only one track) | +| GB45438-003 | The three mandatory metadata fields are documented in the AILABEL | + +--- + +## Sources + +- [GB 45438-2025 — Code of China](https://www.codeofchina.com/standard/GB45438-2025.html) +- [Measures for the Identification of AI-Generated (Synthetic) Content — Regulations.AI](https://regulations.ai/regulations/RAI-CN-NA-MIASCXX-2025) +- [Measures for Labeling of AI-Generated Synthetic Content — China Law Translate](https://www.chinalawtranslate.com/en/ai-labeling/) +- [Adoption of Watermarking Measures for AI-Generated Content — arXiv](https://arxiv.org/html/2503.18156v2) + + diff --git a/.devtrail/00-governance/GIT-BRANCHING-STRATEGY.md b/.straymark/00-governance/GIT-BRANCHING-STRATEGY.md similarity index 98% rename from .devtrail/00-governance/GIT-BRANCHING-STRATEGY.md rename to .straymark/00-governance/GIT-BRANCHING-STRATEGY.md index 7bbf409..c012f1d 100644 --- a/.devtrail/00-governance/GIT-BRANCHING-STRATEGY.md +++ b/.straymark/00-governance/GIT-BRANCHING-STRATEGY.md @@ -90,5 +90,5 @@ git push -u origin fix/accidental-commits --- -*DevTrail v1.0.0 | Last updated: 2025-01-30* +*StrayMark v1.0.0 | Last updated: 2025-01-30* *[Strange Days Tech](https://strangedays.tech) — Because every change tells a story.* diff --git a/.devtrail/00-governance/ISO-25010-2023-REFERENCE.md b/.straymark/00-governance/ISO-25010-2023-REFERENCE.md similarity index 97% rename from .devtrail/00-governance/ISO-25010-2023-REFERENCE.md rename to .straymark/00-governance/ISO-25010-2023-REFERENCE.md index bc4f4b8..e1d53b5 100644 --- a/.devtrail/00-governance/ISO-25010-2023-REFERENCE.md +++ b/.straymark/00-governance/ISO-25010-2023-REFERENCE.md @@ -2,7 +2,7 @@ > **Standard**: ISO/IEC 25010:2023 — Systems and software Quality Requirements and Evaluation (SQuaRE) — Product quality model > **Replaces**: ISO/IEC 25010:2011 -> **Purpose**: Reference document for DevTrail templates (ADR, REQ) that evaluate software quality characteristics. +> **Purpose**: Reference document for StrayMark templates (ADR, REQ) that evaluate software quality characteristics. --- @@ -131,7 +131,7 @@ Degree to which a product achieves acceptable levels of risk to people, business --- -## Usage in DevTrail +## Usage in StrayMark - **TEMPLATE-REQ.md**: Non-Functional Requirements section uses these 9 characteristics as categories - **TEMPLATE-ADR.md**: Consequences section evaluates decisions against relevant quality characteristics @@ -139,7 +139,7 @@ Degree to which a product achieves acceptable levels of risk to people, business ## Key Changes to Remember -When reviewing or creating DevTrail documents: +When reviewing or creating StrayMark documents: 1. Use **"Interaction Capability"** instead of "Usability" 2. Use **"Flexibility"** instead of "Portability" @@ -147,4 +147,4 @@ When reviewing or creating DevTrail documents: 4. **"Resistance"** (under Security) is relevant for threat assessments 5. **"Scalability"** (under Flexibility) is now a formal sub-characteristic - + diff --git a/.devtrail/00-governance/MANAGEMENT-REVIEW-TEMPLATE.md b/.straymark/00-governance/MANAGEMENT-REVIEW-TEMPLATE.md similarity index 94% rename from .devtrail/00-governance/MANAGEMENT-REVIEW-TEMPLATE.md rename to .straymark/00-governance/MANAGEMENT-REVIEW-TEMPLATE.md index 32840e0..36dbe78 100644 --- a/.devtrail/00-governance/MANAGEMENT-REVIEW-TEMPLATE.md +++ b/.straymark/00-governance/MANAGEMENT-REVIEW-TEMPLATE.md @@ -77,7 +77,7 @@ | Incident Response Time | < 24h | [Value] | [Value] | [Up/Down/Stable] | [On target / At risk / Below target] | | Compliance Score | > 75% | [Value] | [Value] | [Up/Down/Stable] | [On target / At risk / Below target] | -> **Source**: Run `devtrail metrics` to collect current values before the review. +> **Source**: Run `straymark metrics` to collect current values before the review. #### 3.2 AI System Status (from AI-LIFECYCLE-TRACKER.md) @@ -105,7 +105,7 @@ |-----------|-------------|----------|-------------------|--------| | [ID] | [Finding description] | [Severity] | [Action taken or planned] | [Open / Closed] | -> **Source**: Run `devtrail compliance --all` to generate compliance report before the review. +> **Source**: Run `straymark compliance --all` to generate compliance report before the review. **Discussion notes**: [Record discussion about audit findings and remediation progress] @@ -133,7 +133,7 @@ |-------|-------------|-----------|-------------------|--------| | NC-[NNN] | [Description of the nonconformity] | [Root cause analysis] | [Corrective action taken or planned] | [Open / In progress / Closed / Verified] | -> **Source**: INC documents in DevTrail and `devtrail compliance` failures. +> **Source**: INC documents in StrayMark and `straymark compliance` failures. **Discussion notes**: [Record discussion about recurring issues and systemic problems] @@ -177,7 +177,7 @@ --- -*Management Review template — DevTrail Framework* +*Management Review template — StrayMark Framework* *Aligned with ISO/IEC 42001:2023 Clause 9.3* - + diff --git a/.devtrail/00-governance/OBSERVABILITY-GUIDE.md b/.straymark/00-governance/OBSERVABILITY-GUIDE.md similarity index 94% rename from .devtrail/00-governance/OBSERVABILITY-GUIDE.md rename to .straymark/00-governance/OBSERVABILITY-GUIDE.md index 5ab45f4..e5023a8 100644 --- a/.devtrail/00-governance/OBSERVABILITY-GUIDE.md +++ b/.straymark/00-governance/OBSERVABILITY-GUIDE.md @@ -1,7 +1,7 @@ -# Observability Guide — OpenTelemetry Integration for DevTrail Projects +# Observability Guide — OpenTelemetry Integration for StrayMark Projects > **This guide is optional.** Adopt it when your project instruments systems with OpenTelemetry. -> It complements the existing DevTrail governance documents and does not replace any of them. +> It complements the existing StrayMark governance documents and does not replace any of them. --- @@ -14,7 +14,7 @@ The guide covers: - **Signals**: which telemetry signals to collect and how they relate to each other - **Configuration**: resource attributes, context propagation, and collector pipelines - **Data policies**: what can and cannot be captured, retention, and security -- **DevTrail integration**: how observability work maps to existing document types +- **StrayMark integration**: how observability work maps to existing document types > **When to activate this guide**: Include it in your project governance when at least one service will emit traces, metrics, or structured logs via OpenTelemetry. Document the decision in an AIDEC or ADR. @@ -59,7 +59,7 @@ Resource attributes identify the source of telemetry data. Configure them once a ## 4. Context Propagation -Context propagation ensures that a single request can be traced across service boundaries. DevTrail projects should use the **W3C Trace Context** standard. +Context propagation ensures that a single request can be traced across service boundaries. StrayMark projects should use the **W3C Trace Context** standard. ### Headers @@ -174,11 +174,11 @@ Rather than trying to block every sensitive field, define an explicit allowlist --- -## 8. DevTrail Integration +## 8. StrayMark Integration -Observability work generates artifacts that must be documented within the DevTrail framework. Use the following mapping to determine which document type to create or update. +Observability work generates artifacts that must be documented within the StrayMark framework. Use the following mapping to determine which document type to create or update. -| Change | DevTrail Document | Notes | +| Change | StrayMark Document | Notes | |--------|-------------------|-------| | Instrumentation changes (new spans, attributes) | **AILOG** | Tag: `observabilidad` | | Backend selection decision | **AIDEC** or **ADR** | Depending on scope; AIDEC for AI-assisted decisions, ADR for architectural decisions | @@ -195,7 +195,7 @@ Observability work generates artifacts that must be documented within the DevTra ## 9. Adoption Roadmap -Adopt OpenTelemetry incrementally. Each phase builds on the previous one and produces specific DevTrail documents. +Adopt OpenTelemetry incrementally. Each phase builds on the previous one and produces specific StrayMark documents. ### Phase 0 — Decision @@ -232,7 +232,7 @@ Adopt OpenTelemetry incrementally. Each phase builds on the previous one and pro ## 10. Checklist -Use this checklist to verify that your project's OpenTelemetry integration is complete and aligned with DevTrail governance. +Use this checklist to verify that your project's OpenTelemetry integration is complete and aligned with StrayMark governance. - [ ] **AIDEC/ADR** documenting the OTel adoption decision and backend selection - [ ] **REQ** with observability requirements and SLOs @@ -248,7 +248,7 @@ Use this checklist to verify that your project's OpenTelemetry integration is co ## Regulatory Alignment -OpenTelemetry instrumentation supports compliance with several regulatory and standards frameworks relevant to DevTrail projects. +OpenTelemetry instrumentation supports compliance with several regulatory and standards frameworks relevant to StrayMark projects. | Standard | Reference | Relevance | |----------|-----------|-----------| @@ -259,8 +259,8 @@ OpenTelemetry instrumentation supports compliance with several regulatory and st | **ISO/IEC 42001** | A.6.2.6 (Operation and Monitoring) | Continuous operational evidence from OTel supports AI management system monitoring requirements | | **ISO/IEC 42001** | A.5.2 (Risk Assessment) | Operational data collected through OTel informs ongoing risk assessment and mitigation | -> **Guidance**: When preparing for audits or compliance reviews, use OTel data exports alongside DevTrail documents (REQ, INC, ETH) to demonstrate continuous monitoring and data governance. +> **Guidance**: When preparing for audits or compliance reviews, use OTel data exports alongside StrayMark documents (REQ, INC, ETH) to demonstrate continuous monitoring and data governance. --- - + diff --git a/.straymark/00-governance/PIPL-PIPIA-GUIDE.md b/.straymark/00-governance/PIPL-PIPIA-GUIDE.md new file mode 100644 index 0000000..db05c06 --- /dev/null +++ b/.straymark/00-governance/PIPL-PIPIA-GUIDE.md @@ -0,0 +1,142 @@ +# PIPL / PIPIA Guide — StrayMark + +> Practical guide for completing a Personal Information Protection Impact Assessment under China's **Personal Information Protection Law** (PIPL), Articles 55-56. + +**Languages**: English | [Español](i18n/es/PIPL-PIPIA-GUIDE.md) | [简体中文](i18n/zh-CN/PIPL-PIPIA-GUIDE.md) + +--- + +## When a PIPIA is Required + +Per **PIPL Art. 55**, a PIPIA must be conducted prior to: + +1. Processing **sensitive personal information** (Art. 28: biometrics, religious beliefs, specific identity, medical health, financial accounts, location tracking, personal information of minors under 14). +2. Using personal information for **automated decision-making**. +3. **Entrusting** processing to a third party / providing data to other personal information handlers / **publicly disclosing** personal information. +4. **Cross-border transfer** of personal information outside mainland China. +5. Other processing activities with **significant impact** on individuals. + +If any apply, set `pipl_applicable: true` on the relevant ETH / MCARD / AILOG and create a PIPIA document. Validation rule **CROSS-005** enforces the link. + +--- + +## PIPIA vs. DPIA + +PIPIA (China) and DPIA (EU GDPR Art. 35) overlap conceptually but differ in detail: + +| Aspect | DPIA (GDPR) | PIPIA (PIPL) | +|--------|------------|--------------| +| Statutory basis | GDPR Art. 35 | PIPL Art. 55-56 | +| Trigger threshold | "High risk" | Any of the five Art. 55 scenarios | +| Required elements | Necessity, risks to data subjects, mitigations, DPO consultation | Lawfulness/legitimacy/necessity, personal-rights impact, security risks, proportionality of safeguards | +| Retention | Not specified by GDPR | **Minimum 3 years** (Art. 56) | +| Authority consultation | Mandatory if residual risk is high | Provincial CAC consulted for cross-border transfer | + +If your organization is subject to **both** GDPR and PIPL for the same processing, the simplest approach is: +- Maintain a **DPIA** as the primary document. +- Maintain a **PIPIA** that cross-references the DPIA via `related: [DPIA-...]` and adds the PIPL-specific elements. + +The DPIA template now includes a *Cross-reference: PIPIA* section that points the other way when `pipl_applicable: true`. + +--- + +## The Three Mandatory Elements of a PIPIA Report (Art. 56) + +A PIPIA must address: + +### 1. Lawfulness / Legitimacy / Necessity + +- **Lawful** — Identify the legal basis under PIPL Art. 13 (consent, contract performance, legal duty, emergency, news reporting, public interest, disclosed-by-individual). +- **Legitimate** — The purpose is clear, reasonable, and disclosed. +- **Necessary** — The minimum data is processed to achieve the purpose. + +### 2. Personal Rights Impact + Security Risks + +- Map each PIPL right (Art. 44-47, plus Art. 24 opt-out for automated decision-making) to a likelihood/severity/mitigation row. +- Identify confidentiality, integrity, availability risks. Use the same scoring scale (low/medium/high) as StrayMark's `risk_level` field. + +### 3. Proportionality of Protective Measures + +- Demonstrate that the measures are **lawful, effective, and commensurate**. +- Document residual risk after each measure. + +--- + +## Cross-Border Transfer (PIPL Art. 38-40) + +Cross-border transfer requires **one** of these mechanisms: + +| Mechanism | When | StrayMark field | +|-----------|------|----------------| +| **CAC Security Assessment** | Required for: Critical Information Infrastructure Operators (CIIO); processors handling personal info of ≥ 1M individuals; cumulative cross-border transfer of personal info of ≥ 100,000 individuals or sensitive personal info of ≥ 10,000 individuals (in any consecutive 12-month period) | `cac_security_assessment_reference` (free-form in PIPIA body) | +| **Personal Information Protection Certification** | Voluntary alternative; granted by accredited body | `pipia_certification_reference` (free-form) | +| **Standard Contract** | Filed with provincial CAC; suitable for smaller volumes | `pipia_standard_contract_filing` (free-form) | + +StrayMark does not currently model these as structured fields beyond `pipl_cross_border_transfer: true` — document the chosen mechanism in the *Cross-Border Transfer Analysis* section of the PIPIA template. + +--- + +## Retention + +Per Art. 56, the PIPIA report and the related "handling-status records" must be **retained for at least three years**. Set `pipl_retention_until: YYYY-MM-DD` to a date at least 3 years from `created`. **TYPE-003** validation enforces this. + +```yaml +created: 2026-04-25 +pipl_retention_until: 2029-04-25 # exactly 3 years — minimum allowed +``` + +--- + +## Sensitive Personal Information Triggers + +Special care is required for these categories (Art. 28): + +- Biometric identification (fingerprint, face, voice, gait) +- Religious beliefs +- Specific identity (e.g., LGBTQ+ status, criminal record) +- Medical health +- Financial accounts +- Location tracking +- Personal information of minors under 14 + +Processing requires **separate consent** and a PIPIA. If your model uses any of these in training or inference: +- Set `pipl_sensitive_data: true` +- Document mitigation in the PIPIA *Protective Measures* section +- Cross-reference the relevant MCARD `## Training Data` section + +--- + +## Personal Information Protection Officer (PIPL Art. 52) + +A handler that processes personal information of **more than 1,000,000 individuals** must designate a Personal Information Protection Officer. If applicable: +- Set `dpo_consulted: true` on the PIPIA after PIPO consultation +- Document the PIPO's opinion in the *Consultation* section + +--- + +## Worked Example: Customer Chatbot + +A SaaS chatbot deployed in mainland China that: +- Stores conversation history (personal info) +- Uses an LLM for automated responses (automated decision-making) +- Sends some queries to an overseas inference endpoint (cross-border) + +**Triggers**: 1, 2, 4 → PIPIA required. + +**Frontmatter**: +```yaml +id: PIPIA-2026-04-25-001 +pipl_applicable: true +pipl_article_55_trigger: cross_border # primary trigger +pipl_sensitive_data: false +pipl_cross_border_transfer: true +pipl_retention_until: 2029-04-25 +related: + - MCARD-2026-04-25-001 # the LLM + - TC260RA-2026-04-25-001 + - DPIA-2026-04-25-001 # if also GDPR-subject +``` + +**Sections to focus on**: cross-border analysis, automated decision-making (Art. 24 opt-out), legal basis (likely consent), recipient safeguards. + + diff --git a/.devtrail/00-governance/PRINCIPLES.md b/.straymark/00-governance/PRINCIPLES.md similarity index 63% rename from .devtrail/00-governance/PRINCIPLES.md rename to .straymark/00-governance/PRINCIPLES.md index 4a9638c..92d00ca 100644 --- a/.devtrail/00-governance/PRINCIPLES.md +++ b/.straymark/00-governance/PRINCIPLES.md @@ -1,7 +1,9 @@ -# Guiding Principles - DevTrail +# Guiding Principles - StrayMark > These principles guide all documentation decisions in the project. +**Languages**: English | [Español](i18n/es/PRINCIPLES.md) | [简体中文](i18n/zh-CN/PRINCIPLES.md) + --- ## 1. Total Traceability @@ -74,4 +76,16 @@ Certain types of changes **always** require human approval: --- -*DevTrail v1.0.0 | [Strange Days Tech](https://strangedays.tech)* +## 8. Cross-Source Dissonance Surfacing + +> **"When two canonical sources disagree, surface before proceeding."** + +When the agent detects material divergence between two canonical sources of StrayMark documentation (spec ↔ code, AILOG `§Risk` ↔ TDE backlog, ADR ↔ implementation, Charter declared scope ↔ commits, etc.), surface it before proceeding with the asked task. + +StrayMark documentation is deliberately designed to make these divergences detectable: formal cross-referencing (frontmatter fields, canonical sections, stable IDs) + cultural permission to surface beyond the task. The agent's role is to consume that infrastructure and report what it sees. + +See [`EMERGENT-OBSERVATION-DESIGN.md`](EMERGENT-OBSERVATION-DESIGN.md) for the meta-pattern and the pyramid of existing applications. + +--- + +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.devtrail/00-governance/QUICK-REFERENCE.md b/.straymark/00-governance/QUICK-REFERENCE.md similarity index 51% rename from .devtrail/00-governance/QUICK-REFERENCE.md rename to .straymark/00-governance/QUICK-REFERENCE.md index f925f78..bd9d837 100644 --- a/.devtrail/00-governance/QUICK-REFERENCE.md +++ b/.straymark/00-governance/QUICK-REFERENCE.md @@ -1,16 +1,16 @@ -# DevTrail - Quick Reference +# StrayMark - Quick Reference > One-page reference for AI agents and developers. > > **This is a derived document** — DOCUMENTATION-POLICY.md is the authoritative source. -**Languages**: English | [Español](i18n/es/QUICK-REFERENCE.md) +**Languages**: English | [Español](i18n/es/QUICK-REFERENCE.md) | [简体中文](i18n/zh-CN/QUICK-REFERENCE.md) --- ## Language Configuration -**File**: `.devtrail/config.yml` +**File**: `.straymark/config.yml` ```yaml language: en # Options: en, es (default: en) @@ -18,8 +18,8 @@ language: en # Options: en, es (default: en) | Language | Templates Path | |----------|---------------| -| `en` | `.devtrail/templates/TEMPLATE-*.md` | -| `es` | `.devtrail/templates/i18n/es/TEMPLATE-*.md` | +| `en` | `.straymark/templates/TEMPLATE-*.md` | +| `es` | `.straymark/templates/i18n/es/TEMPLATE-*.md` | --- @@ -33,7 +33,7 @@ language: en # Options: en, es (default: en) --- -## Document Types (12) +## Document Types (16) ### Core Types (8) @@ -57,19 +57,40 @@ language: en # Options: en, es (default: en) | `SBOM` | Software Bill of Materials | `07-ai-audit/` | Create freely | | `DPIA` | Data Protection Impact Assessment | `07-ai-audit/ethical-reviews/` | Draft → approval (always) | +### China Regulatory Types (4) — opt-in via `regional_scope: china` + +| Type | Name | Folder | Agent Autonomy | +|------|------|--------|---------------| +| `PIPIA` | Personal Information Protection Impact Assessment (PIPL Art. 55-56) | `07-ai-audit/ethical-reviews/` | Draft → approval (always) | +| `CACFILE` | CAC Algorithm Filing | `07-ai-audit/regulatory-filings/` | Draft → approval (always) | +| `TC260RA` | TC260 v2.0 Risk Assessment | `07-ai-audit/risk-assessments/` | Draft → approval (always) | +| `AILABEL` | GB 45438 Content Labeling Plan | `09-ai-models/labeling/` | Draft → approval (always) | + +### Bounded Units of Work — Charter + +Charters are **not** doc types — they wrap a multi-session implementation block. Filename uses a sequential prefix (`NN-slug.md`), not a date prefix. Lifecycle: `declared` → `in-progress` → `closed`. + +| Concept | Folder | Agent Autonomy | +|---------|--------|---------------| +| `Charter` | `.straymark/charters/` (declarative `NN-slug.md` + telemetry `NN-slug.telemetry.yaml`) | Scaffold via `charter new`; operator owns trigger and lifecycle transitions | + +> See section 15 of `STRAYMARK.md` and `.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md` for granularity heuristics, lifecycle, and the SpecKit ↔ Charter bridge. + --- ## When to Document | Situation | Action | |-----------|--------| -| Complex code (`devtrail analyze`; fallback: >20 lines) | AILOG | +| Complex code (`straymark analyze`; fallback: >20 lines) | AILOG | | Decision between alternatives | AIDEC | | Auth/authorization/PII changes | AILOG + `risk_level: high` + ETH | | Public API or DB schema changes | AILOG + consider ADR | | ML model/prompt changes | AILOG + human review | | Security-critical dependency changes | AILOG + human review | | OTel instrumentation changes | AILOG + tag `observabilidad` | +| Multi-session implementation block (>1 day, >5 tasks across phases) | Declare a **Charter** (`straymark charter new`) | +| Transversal technical debt (heritage from prior Charter, applies to multiple modules, requires dedicated Charter, needs human prioritization) | **TDE** — distinct from per-Charter `R`; see AGENT-RULES.md §3 | **DO NOT document**: credentials, tokens, PII, secrets. @@ -114,8 +135,8 @@ Mark `review_required: true` when: ## Folder Structure ``` -.devtrail/ -├── 00-governance/ ← Policies, AI-GOVERNANCE-POLICY.md +.straymark/ +├── 00-governance/ ← Policies, AI-GOVERNANCE-POLICY.md, CHINA-REGULATORY-FRAMEWORK.md* ├── 01-requirements/ ← REQ ├── 02-design/decisions/ ← ADR ├── 03-implementation/ ← Guides @@ -125,10 +146,16 @@ Mark `review_required: true` when: ├── 07-ai-audit/ │ ├── agent-logs/ ← AILOG │ ├── decisions/ ← AIDEC -│ └── ethical-reviews/ ← ETH, DPIA +│ ├── ethical-reviews/ ← ETH, DPIA, PIPIA* +│ ├── regulatory-filings/ ← CACFILE* +│ └── risk-assessments/ ← TC260RA* ├── 08-security/ ← SEC ├── 09-ai-models/ ← MCARD -└── templates/ ← Templates +│ └── labeling/ ← AILABEL* +├── charters/ ← Charter (NN-slug.md + NN-slug.telemetry.yaml) +└── templates/ ← Templates (incl. charter/ subdir) + +* Only created when regional_scope: china is enabled. ``` --- @@ -178,14 +205,40 @@ Mark `review_required: true` when: | OpenTelemetry | Optional — see OBSERVABILITY-GUIDE | | C4 Model | ADR diagrams — see C4-DIAGRAM-GUIDE | +### China — opt-in via `regional_scope: china` + +| Standard | Key Documents | +|----------|--------------| +| TC260 AI Safety Governance Framework v2.0 | TC260RA — see TC260-IMPLEMENTATION-GUIDE | +| PIPL / PIPIA (Art. 55-56) | PIPIA — see PIPL-PIPIA-GUIDE | +| GB 45438-2025 (AI content labeling, mandatory) | AILABEL — see GB-45438-LABELING-GUIDE | +| CAC Algorithm Filing | CACFILE — see CAC-FILING-GUIDE | +| GB/T 45652-2025 (training-data security) | SBOM, MCARD | +| CSL 2026 (incident reporting amendments) | INC (CSL fields) | + --- ## Skills (Claude Code) | Command | Purpose | |---------|---------| -| `/devtrail-status` | Check documentation status and compliance | +| `/straymark-status` | Check documentation status and compliance | +| `/straymark-new` | Create any document type (interactive) | +| `/straymark-ailog` / `/straymark-aidec` / `/straymark-adr` | Quick shortcuts for AILOG / AIDEC / ADR | +| `/straymark-mcard` / `/straymark-sec` | Interactive flows for Model Card / SEC assessment | +| `/straymark-charter-new` | Scaffold a Charter (declarative ex-ante work unit) | +| `/straymark-audit-prompt CHARTER-XX` *(fw-4.9.0+, refactored in fw-4.9.0)* | External multi-model audit — write unified prompt at canonical path | +| `/straymark-audit-execute [CHARTER-XX]` *(fw-4.9.0+)* | Run inside an auditor CLI — read prompt, audit with tool use, write report | +| `/straymark-audit-review CHARTER-XX` *(fw-4.9.0+, expanded in fw-4.9.0)* | Consolidate N reports into review.md (6 sections) + merge YAML into telemetry | + +--- + +## Patterns + +| Pattern | Document | +|---------|----------| +| Follow-ups backlog (central registry + drift detection) *(fw-4.10.0+)* | [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) | --- -*DevTrail v4.1.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md b/.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md new file mode 100644 index 0000000..d45b991 --- /dev/null +++ b/.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md @@ -0,0 +1,245 @@ +# SpecKit ↔ StrayMark Charter Bridge + +> **Status**: Empirical pattern (`v0`). Crystallizes after validation against a second domain (Principle #12). Refine via PRs as new use cases surface. + +## Problem this document solves + +[SpecKit](https://github.com/StrangeDaysTech/speckit) gives you `spec.md`, `plan.md`, and `tasks.md` for a feature. StrayMark gives you Charters, AILOGs, AIDECs, ADRs. **No canonical doc explained when a SpecKit feature should yield a Charter, how granular it should be, who triggers the creation, or when.** Reported as the central artifact of [issue #113](https://github.com/StrangeDaysTech/straymark/issues/113) — a discoverability gap that left agents (Claude, Gemini, Copilot) building binary mental models (`SpecKit = planning, StrayMark = audit-trail`) and silently dropping the third layer (work-as-auditable-shippable-unit) where Charters live. + +This file is the answer. + +## Mental model + +Three layers, with handoffs: + +| Layer | Lives in | Purpose | Owner | +|-------|----------|---------|-------| +| **1. Specification** | `specs/NNN-feature/{spec,plan,tasks,research,quickstart}.md` | What the feature is, why it exists, how it'll be implemented at a technical level. SpecKit's `/speckit-specify` → `/speckit-plan` → `/speckit-tasks` produces these. | Operator (with agent assist). | +| **2. Bounded execution unit** | `.straymark/charters/NN-slug.md` | The contract for a single shippable cut of the feature. Pairs ex-ante scope (files, risks, tasks subset) with ex-post telemetry (drift, audit, lessons). | Operator declares the Charter; agent executes within it. | +| **3. Implementation trace** | `.straymark/07-ai-audit/agent-logs/AILOG-*.md` (and AIDECs, ADRs as warranted) | Day-to-day record of what was actually done, why, with what confidence. Each AILOG references the Charter via `originating_charter:` (or the Charter aggregates them via `originating_ailogs:`). | Agent creates as it works; operator reviews. | + +**The bridge is the Charter.** Specs are too high-level to drift-check ("did you ship the spec?" is unanswerable in a useful timeframe). AILOGs are too low-level to ship against ("did you ship this AILOG?" is the wrong unit). Charters sit at the right granularity: a stable scope contract you can audit against in days, not months. + +## When does a SpecKit feature yield a Charter? + +A SpecKit feature should produce **at least one Charter** when *any* of the following hold: + +1. The feature's `tasks.md` has **5 or more tasks** that you cannot complete in a single session. +2. The feature spans **2 or more SpecKit phases** (Setup, Foundation, User Stories, Polish, etc.) that you intend to ship together as one unit. +3. The work warrants **external audit** (cross-model review, cross-team review) at completion. +4. You want **measurable telemetry** at close (effort estimate vs. actual, drift count, lessons). + +It should **not** produce a Charter when: + +- The feature is small enough to ship in one session (<1 day, <5 tasks). Use AILOGs alone — the Charter overhead exceeds the auditability gain. +- The feature is **purely planning** (no code yet). Wait until `tasks.md` exists; the Charter contract needs concrete tasks to enumerate. +- The feature is **maintenance** without a planned scope (e.g., "fix bugs as they come"). For ad-hoc maintenance, AILOGs are sufficient. + +## Granularity heuristics + +When a feature warrants Charters, choose granularity by **shippable unit**, not by structural unit. Concretely: + +### Heuristic 1 — One Charter per shippable cut + +If the feature has Phases (e.g., SpecKit's typical Foundation → US1 → US2 → US3 → Polish), the **first Charter wraps the foundation cut** (everything that ships together as `v0.1`). Subsequent Charters wrap subsequent cuts. Effort estimate **M** is the median bucket for a shippable cut; **L** for a full-feature cut. + +``` +specs/001-peek-mvp-foundation/ +├── spec.md +├── plan.md +└── tasks.md → CHARTER-01 (Foundation: T001-T012, effort M) + CHARTER-02 (peek MVP: T013-T044, effort L) +``` + +### Heuristic 2 — NOT per User Story + +User Stories are too granular. A US that takes 2-3 tasks belongs *inside* a Charter, not as its own Charter. Telemetry per US is noise; telemetry per shippable cut is signal. + +### Heuristic 3 — NOT per feature + +A feature that ships in two cuts (e.g., MVP → polish) deserves two Charters, not one. The Charter contract you can drift-check is "what shipped in this cut", not "what we eventually built". + +### Heuristic 4 — Edge case: ≥10 tasks across 4+ phases + +When a feature is exceptionally large, a third Charter (or splitting the foundation cut into "scaffolding" + "core") may be warranted. Use effort estimate **L** as the cap; if you'd estimate **XL**, that's a sign the feature should be re-specified. + +## Creation timing + +``` +/speckit-specify → spec.md +/speckit-plan → plan.md +/speckit-tasks → tasks.md + ↓ + ┌────────────────────────────────────────┐ + │ ★ CHARTER DECLARATION POINT ★ │ + │ │ + │ Operator runs `straymark charter new` │ + │ --from-spec specs/NNN-feature/spec.md│ + │ --type │ + │ │ + │ Charter status: declared │ + │ → Operator fills scope, files, tasks │ + │ → status: in-progress when execute │ + └────────────────────────────────────────┘ + ↓ +/speckit-implement → tasks executed + → AILOGs created (`originating_charter:` → Charter) + ↓ +straymark charter drift CHARTER-NN → file-vs-commit check +straymark charter audit CHARTER-NN → external audit (optional) +straymark charter close CHARTER-NN → telemetry, status: closed +``` + +**Key invariant**: declare the Charter *before* `/speckit-implement` starts. The Charter is a contract; declaring it after execution defeats the drift check. + +## Frontmatter linkage + +The Charter's frontmatter explicitly cites the SpecKit feature: + +```yaml +charter_id: CHARTER-01-workspace-foundation +status: declared +effort_estimate: M +trigger: tasks.md has 12 ordered tasks across 2 phases; ship as v0.1. +originating_spec: specs/001-peek-mvp-foundation/spec.md +``` + +The reverse direction (spec → Charter) is by convention — list the active Charter in the spec's "Phase 5: Implementation Tracking" section if your `plan.md` template has one. SpecKit currently has no schema slot for this; emerging convention. + +AILOGs created during execution should cite the Charter: + +```yaml +id: AILOG-2026-05-08-005 +title: T013, T016-T026 — US1 P1 MVP core + TUI + peek bin +agent: claude-code-v4.7 +confidence: high +risk_level: medium +review_required: false +originating_charter: CHARTER-02-peek-mvp-foundation +``` + +## Lifecycle map + +| SpecKit phase | Charter event | StrayMark CLI | +|---------------|---------------|---------------| +| `/speckit-tasks` complete | **Declare Charter** | `/straymark-charter-new` skill or `straymark charter new --from-spec …` | +| First task starts | Operator flips `declared` → `in-progress` | (manual frontmatter edit) | +| Each task executed | AILOG produced (when warranted by §6 of STRAYMARK.md) | `/straymark-ailog` | +| Major decision encountered | AIDEC produced | `/straymark-aidec` | +| Architectural shift | ADR produced | `/straymark-adr` | +| Last task done, before close | Drift check | `straymark charter drift CHARTER-NN` | +| Optional external review | Multi-model audit | `straymark charter audit CHARTER-NN` + `/straymark-audit-prompt` + `/straymark-audit-execute` + `/straymark-audit-review` | +| Cut shipped | Close Charter | `straymark charter close CHARTER-NN` (status: `closed`, telemetry yaml emitted) | + +## Spec maintenance during multi-Charter execution + +> **Empirical anchor**: surfaced by [issue #150](https://github.com/StrangeDaysTech/straymark/issues/150) after Sentinel ran a single `specs/002-commshub/plan.md` (committed 2026-04-21) through **seven consecutive Charters** (CHARTER-07 through CHARTER-17, ~1 month). Twelve aprendizajes empíricos that materially impact the next Charter's scope were *not* reflected in the plan. The pattern below codifies what Sentinel discovered before CHARTER-18 fill. +> +> **Canonical extension** *(fw-4.16.0+)*: this section's procedural guidance (when + how + gates) is the mechanical floor. The *named pattern* — including the `r_n_plus_one_emergent_count` rolling-mean trigger heuristic, the categorized-learnings table contract, telemetry slot `pre_declare_refresh:`, and the `straymark charter refresh-suggest` helper — lives in [CHARTER-CHAIN-EVOLUTION.md](CHARTER-CHAIN-EVOLUTION.md) **Pattern 1**. Read both: this doc tells you the *how*, that one names the *pattern* and feeds it back into telemetry. + +The lifecycle map above assumes **one-pass**: SpecKit artifacts are generated once, then Charters are declared and executed. This scales fine for features that produce a single Charter. When a single spec drives many Charters spaced weeks apart, **planning artifacts drift relative to shipped code** — and naively re-running `/speckit-plan` is *worse*, not better: regeneration asserts things about already-shipped user stories that the actual code does not implement, and future readers (auditors, agents, new operators) trust those regenerated artifacts as ground truth. + +This section answers **how**, not **whether**: what discipline keeps the spec in sync with code during multi-Charter execution **without** the regeneration step lying about the parts that already shipped. + +### When to refresh + +A spec-refresh is warranted when *any* of the following hold: + +1. **≥3 Charters closed against the same spec** — the volume of unreflected execution detail is high enough that the next Charter's scope decisions risk inheriting stale premises. +2. **≥4 calendar weeks** since the spec was last refreshed (or since initial generation) and ≥2 Charters closed in that window. +3. **AILOG `## Risk: R(new, not in Charter)` count on the spec exceeds ~6 across closed Charters** — the spec's anticipation of risk has measurably under-described the territory. +4. **The next Charter's user story touches infrastructure the prior Charters refined empirically** (new tables/migrations created, helpers extracted, contracts crystallized) and the spec describes the pre-refinement state. + +If none hold and the next Charter targets a fresh sub-system the prior Charters didn't touch, **skip the refresh**. Spec stability has value; refreshing on every Charter creates churn without proportional clarity gain. + +### How to refresh: scope-limited prompt + +Do **not** re-run `/speckit-plan` with a blank slate. The regenerated `plan.md` + `research.md` + `data-model.md` + `contracts/` + `quickstart.md` will assert things about already-shipped user stories that the actual code does not implement. + +Instead, invoke `/speckit-plan` with a **scope-limited prompt** that: + +1. **Names the target phase explicitly** (e.g., "refresh planning for US5 only — failover + tracking"). +2. **Lists locked sections that must not change** (e.g., "Foundation, US1, US2, US3, US4 sections are immutable — the code shipped against them is the ground truth, not the plan"). +3. **Cites the AILOGs that document refinements** (e.g., "see AILOG-2026-05-11-043 §R5 for the `processed_events` reuse pattern; reflect this in the refreshed data model"). +4. **Forbids regenerating `tasks.md`** — see next subsection. + +The output is a `plan.md` (and possibly `research.md` / `data-model.md` / `contracts/`) where the target-phase content is fresh and the locked sections carry forward the actually-shipped state, not the original aspirational state. + +### Three mechanical gates post-refresh + +Before merging the spec-refresh PR, three gates run sequentially: + +**Gate (a) — Validation against code reality.** +For each non-target-phase entity in `data-model.md`, diff against the actual `db/migrations/*.sql` (or equivalent schema source). For each non-target-phase endpoint in `contracts/*.md`, diff against actual handler signatures. Any divergence in a *locked* section blocks merge — that's the regeneration lying. Adopters may script this against their stack; a CLI helper (`straymark spec-drift`) is on the roadmap (see #150 Ask 3). + +**Gate (b) — Granular diff hunk-by-hunk review.** +Run `git diff specs/NNN-feature/` and review file-by-file, hunk-by-hunk. No changes to locked sections accepted without an explicit justification comment in the PR. The diff is small enough when scope-limited that this is feasible in one sitting. + +**Gate (c) — Two-PR split.** +Land the spec-refresh as its own PR. Review it against the *code*, not against the plan-only output. Then fill the target Charter against the refreshed spec in a *separate* PR. Mixing the two collapses review surfaces: reviewers can no longer tell whether a hunk reflects new shipped state or new planned state. + +### Why NOT re-run `/speckit-tasks` mid-spec-execution + +The `tasks.md` file accumulates implementation trace state during execution: `[X]` checkboxes on completed tasks, `*CHARTER-NN: *` annotations citing which Charter shipped which task, possibly `^skipped` markers with rationale. **Regenerating `tasks.md` destroys this state.** The file becomes a fresh task list with no record of what already shipped. + +Discipline: **never** re-run `/speckit-tasks` while a spec is in the middle of multi-Charter execution. Instead, **manually edit `tasks.md`** for the target phase only — append new tasks for the refreshed scope, leave the already-shipped sections (`[X]` + `*CHARTER-NN:*` annotations) untouched. + +If you discover that the original `tasks.md` had errors in shipped sections (e.g., a task was incorrectly marked `[X]` when its work was actually split across two Charters), correct it manually with a Git commit. Treat `tasks.md` as a historical record from the point of first execution onward; it is no longer a regeneratable artifact. + +### Constitution Check re-evaluation cadence + +SpecKit's Constitution Check is typically run once at `/speckit-plan` time. In multi-Charter execution against a single spec, the question of *when* to re-evaluate is left implicit. To make this explicit: + +- **Per-Charter (recommended)** — re-evaluate Constitution Check at the start of each new Charter declared against the spec. The check is cheap (read the constitution; compare against the Charter's declared scope) and catches drift early, before execution commits. +- **Per-spec-refresh (mandatory when the refresh happens)** — when a scope-limited `/speckit-plan` refresh lands, the refresh PR must re-run Constitution Check against the refreshed plan. If the framework version moved (e.g., `fw-4.10.x → fw-4.14.x`), Constitution Check may yield different results because new gates exist. +- **NOT per-framework-bump alone** — a `straymark update-framework` between Charters does *not* require an immediate Constitution Check re-run on the open spec. The check applies at the next natural boundary (next Charter declaration or spec-refresh). + +Codifying this as explicit cadence (rather than "whoever decides") closes a recurring ambiguity reported by Sentinel post-CHARTER-17. + +### Roadmap: `straymark spec-drift` + +A CLI command analogous to `straymark charter drift`, but operating at spec granularity — parse `data-model.md` → entities → diff against `db/migrations/*.sql`; parse `contracts/*.md` → endpoints → diff against handler signatures. It would mechanize Gate (a) above. + +Deferred deliberately to a post-announcement Charter (tracked separately). The CLI surface is meaningful only for adopters whose spec format follows SpecKit conventions; the language-detection layer (Go vs Rust vs TypeScript vs Python handlers; SQL vs ORM-defined schemas) is non-trivial and warrants its own design cycle informed by real adopter stacks. The discipline above (Gates a/b/c executed manually) is the v0; the CLI is the v1 that mechanizes the most expensive gate. + +## Anti-patterns + +**Don't open a Charter "to be safe".** A Charter without a clear shippable cut becomes a wishlist. Operators end up closing it as `closed: aborted` and the telemetry is meaningless. + +**Don't open a Charter per User Story.** Telemetry-per-US is too noisy to inform future estimates. Aggregate. + +**Don't skip the `originating_spec` field.** Even if the Charter wraps work that doesn't have a SpecKit spec, set `originating_ailogs:` instead. Charters with no origin are an anti-pattern (they signal undocumented motivation). + +**Don't run `straymark charter audit` without the auditor CLIs available.** The audit is orchestration-only — `straymark` does not call LLM APIs. If you don't have N auditor CLIs ready, skip the step; close the Charter without external audit. + +**Don't flip status to `closed` before drift check + telemetry yaml.** `straymark charter close` does both atomically; manual closure skips invariants. + +**Don't re-run `/speckit-tasks` mid-spec-execution.** Regenerating `tasks.md` destroys the `[X]` completion marks and `*CHARTER-NN:* …` annotations that form the historical trace. See "Spec maintenance during multi-Charter execution" above for the safe path (manual edit for the target phase only). + +## When this pattern doesn't fit + +This bridge assumes a SpecKit-driven feature flow with multi-task, multi-session implementation. It does not fit: + +- **Single-session features** — use AILOGs alone. +- **Architecture-only work with no implementation** (e.g., "design the next-gen schema") — use ADRs. +- **Pure refactors with no new behavior** — use AILOGs + tag with `refactor:`. +- **Incident response and hotfixes** — use INC + AILOG. +- **Compliance-only deliverables** (e.g., quarterly DPIA refresh) — use the relevant doc type directly. + +If your work fits one of those, *declare no Charter*. The cost of a Charter exceeds the value when there's no shippable cut to wrap. + +## See also + +- [`EMERGENT-OBSERVATION-DESIGN.md`](EMERGENT-OBSERVATION-DESIGN.md) — the meta-pattern that explains *why* multi-source linkage in this bridge produces emergent observations during multi-Charter execution. +- `STRAYMARK.md` §6 (When to Document) and §15 (Charters as bounded units of work) +- `.straymark/templates/charter/charter-template.md` — declarative template +- `.straymark/templates/charter/charter-telemetry-template.yaml` — telemetry template +- `.straymark/schemas/charter.schema.v0.json` — JSON Schema for declarative frontmatter +- `.straymark/schemas/charter-telemetry.schema.v0.json` — JSON Schema for telemetry +- `.claude/skills/straymark-charter-new/SKILL.md` (and Gemini / agnostic equivalents) + +> **Cited the empirical context** (issue #113): Greenfield Rust CLI/TUI suite, Claude Opus 4.7 onboarding via canonical entry points (`STRAYMARK.md`, project constitution, `CLAUDE.md` checklist, available `/straymark-*` skills, `/straymark-status`). Charters were *eventually* adopted (2 Charters: foundation + MVP) only after explicit user prompt — confirming the gap was systemic, not session-specific. This document removes the gap. + +--- + +*Languages*: English | [Español](i18n/es/SPECKIT-CHARTER-BRIDGE.md) | [简体中文](i18n/zh-CN/SPECKIT-CHARTER-BRIDGE.md) diff --git a/.straymark/00-governance/TC260-IMPLEMENTATION-GUIDE.md b/.straymark/00-governance/TC260-IMPLEMENTATION-GUIDE.md new file mode 100644 index 0000000..af30713 --- /dev/null +++ b/.straymark/00-governance/TC260-IMPLEMENTATION-GUIDE.md @@ -0,0 +1,147 @@ +# TC260 Implementation Guide — StrayMark + +> Practical guide for completing a TC260RA document according to the **AI Safety Governance Framework v2.0** (TC260, 15 Sep 2025). + +**Languages**: English | [Español](i18n/es/TC260-IMPLEMENTATION-GUIDE.md) | [简体中文](i18n/zh-CN/TC260-IMPLEMENTATION-GUIDE.md) + +--- + +## When to Create a TC260RA + +Create a TC260 Risk Assessment when **any** of the following applies and `regional_scope` includes `china`: + +- The system you are deploying or modifying is or includes an AI model. +- The application is destined for users in mainland China, or the operator is incorporated in mainland China. +- The system has cross-border data flows that touch mainland China. +- A new model version, scenario, or scale jump is anticipated. + +A TC260RA complements the EU AI Act risk classification on ETH and is referenced via `related: [TC260RA-...]` from the relevant ETH / MCARD / AILOG. + +--- + +## The Three Criteria + +TC260 v2.0 grades risk along **three orthogonal axes**, then composes them into a single level (low / medium / high / very_high / extremely_severe). + +### 1. Application Scenario (`tc260_application_scenario`) + +What domain does the system operate in? Some scenarios are inherently higher-risk because errors translate into physical, financial, or societal harm. + +| Scenario | Examples | Inherent risk floor | +|----------|----------|---------------------| +| `public_service` | Government chatbots, public information portals | medium | +| `healthcare` | Clinical decision support, medical imaging | high | +| `finance` | Credit scoring, KYC, fraud detection | high | +| `safety_critical` | Autonomous driving, industrial control, energy | very_high | +| `content_generation` | Text/image/video synthesis | medium | +| `social` | Recommendation, ranking, dating | medium | +| `industrial_control` | OT systems, robotics | very_high | +| `other` | Document briefly | — | + +### 2. Level of Intelligence (`tc260_intelligence_level`) + +How autonomous is the system? + +| Level | Definition | +|-------|-----------| +| `narrow` | Single-purpose, deterministic outputs in a well-defined task | +| `foundation` | General-purpose foundation model (LLM, vision-language) without tool use | +| `agentic` | Foundation model + autonomous tool use, can take real-world actions | +| `general` | Approaching AGI — broad cross-domain competence | + +### 3. Application Scale (`tc260_application_scale`) + +How many users / how broad the impact? + +| Scale | Definition | +|-------|-----------| +| `individual` | Single user / small team | +| `organization` | Single organization or enterprise | +| `societal` | Significant portion of the public (≥ 1M users) | +| `cross_border` | Operates across mainland China and other jurisdictions | + +--- + +## Composing the Level + +There is no published numeric formula. Use the matrix below as a starting point and document the reasoning. + +| Scenario \ Intelligence | Narrow | Foundation | Agentic | General | +|-------------------------|--------|-----------|---------|---------| +| public_service | low → medium | medium | high | very_high | +| healthcare / finance | medium | high | high | very_high | +| safety_critical | high | very_high | very_high | extremely_severe | +| content_generation | low | medium | high | very_high | +| social | low | medium | high | very_high | +| industrial_control | high | very_high | very_high | extremely_severe | + +**Scale modifier**: +- `individual` → no change. +- `organization` → no change. +- `societal` → bump one level (low→medium, medium→high, etc.). +- `cross_border` → bump one level **and** require explicit cross-border data analysis (see PIPL-PIPIA-GUIDE). + +Always document the reasoning in section 2.4 of the TC260RA template — auditors will care about why, not what. + +--- + +## Risk Taxonomy: How to Populate + +The taxonomy in v2.0 distinguishes three families: + +### Endogenous (`tc260_endogenous_risks`) + +Inherent to the model: +- `hallucination` — confabulation, unsupported claims +- `bias` — protected-class disparities +- `robustness` — adversarial vulnerability +- `data_leakage` — training-data extraction +- `prompt_injection` +- `model_extraction` + +### Application (`tc260_application_risks`) + +Arising from technical use: +- `misuse` — repurposing for harmful tasks +- `scope_creep` — used beyond intended domain +- `dependency` — over-reliance on AI judgments +- `availability` — single point of failure for critical workflows +- `integration_flaw` — unsafe coupling with downstream systems + +### Derivative (`tc260_derivative_risks`) + +Second-order societal effects: +- `labor_displacement` +- `opinion_shaping` +- `ecosystem_disruption` +- `monoculture` — homogenization of outputs +- `loss_of_skill` + +For `very_high` and `extremely_severe` levels, v2.0 explicitly requires **catastrophic-risk monitoring**: document this in section 5 (Governance Measures) of the TC260RA. + +--- + +## Linking from Other Documents + +When `tc260_risk_level: high` (or higher) is set on a non-TC260RA document, validation rule **CROSS-004** requires `review_required: true`. The TC260RA itself should be linked via `related:`: + +```yaml +# Example: ETH document for a high-risk healthcare LLM +related: + - TC260RA-2026-04-25-001 + - MCARD-2026-04-25-001 + - PIPIA-2026-04-25-001 +``` + +--- + +## Review Cadence + +| Trigger | Action | +|---------|--------| +| Model version change | Re-run section 4 (technical countermeasures) | +| Scenario expansion | Re-grade scenario × intelligence × scale | +| Scale crossing a tier (e.g., 1M users) | Bump level review | +| Regulatory update from TC260 | Full re-review | + + diff --git a/.devtrail/00-governance/exceptions/.gitkeep b/.straymark/00-governance/exceptions/.gitkeep similarity index 100% rename from .devtrail/00-governance/exceptions/.gitkeep rename to .straymark/00-governance/exceptions/.gitkeep diff --git a/.straymark/00-governance/i18n/es/AGENT-RULES.md b/.straymark/00-governance/i18n/es/AGENT-RULES.md new file mode 100644 index 0000000..93195c3 --- /dev/null +++ b/.straymark/00-governance/i18n/es/AGENT-RULES.md @@ -0,0 +1,390 @@ +# Reglas para Agentes IA - StrayMark + +> Este documento define las reglas que todos los agentes de IA deben seguir cuando trabajan en proyectos bajo StrayMark. + +**Idiomas**: [English](../../AGENT-RULES.md) | Español | [简体中文](../zh-CN/AGENT-RULES.md) + +--- + +## 1. Identificación Obligatoria + +### Al Iniciar una Sesión + +Cada agente debe identificarse con: +- Nombre del agente (ej.: `claude-code-v1.0`, `cursor-v1.0`, `gemini-cli-v1.0`) +- Versión del agente si está disponible + +### En Cada Documento + +Incluir en el frontmatter: +```yaml +agent: agent-name-v1.0 +confidence: high | medium | low +``` + +--- + +## 2. Cuándo Documentar + +### OBLIGATORIO - Crear documento + +| Situación | Tipo | Notas | +|-----------|------|-------| +| Complejidad de código sobre el umbral | AILOG | Ejecutar `straymark analyze --output json`. Si `summary.above_threshold > 0`, crear AILOG (umbral por defecto: 8). **Alternativa**: si el CLI no está disponible, usar heurística de >20 líneas de lógica de negocio | +| Decisión entre 2+ alternativas técnicas | AIDEC | Documentar alternativas | +| Cambios en auth/autorización/PII | AILOG + ETH | `risk_level: high`, ETH requiere aprobación | +| Cambios en API pública o esquema de BD | AILOG | `risk_level: medium+`, considerar ADR | +| Cambios en modelos ML o prompts de IA | AILOG | `risk_level: medium+`, revisión humana requerida | +| Integración con servicio externo | AILOG | - | +| Adición/eliminación/actualización de dependencias críticas de seguridad | AILOG | Revisión humana requerida | +| Cambios que afectan el ciclo de vida del sistema de IA (despliegue, retirada) | AILOG + ADR | Revisión humana requerida | +| Cambios en instrumentación OTel (spans, atributos, pipeline) | AILOG | Tag `observabilidad`, ver §9 | +| Deuda técnica transversal detectada durante la implementación | TDE | Ver §3 "TDE vs `R` (new, not in Charter)" para el criterio de desambiguación | + +### PROHIBIDO - No documentar + +- Credenciales, tokens, API keys +- Información personal identificable +- Secretos de cualquier tipo + +### OPCIONAL - No requiere documento + +- Cambios de formato (espacios, indentación) +- Correcciones de erratas +- Comentarios de código +- Cambios menores de estilo + +--- + +## 3. Límites de Autonomía + +### Crear Libremente + +| Tipo | Descripción | +|------|-------------| +| AILOG | Logs de acciones realizadas | +| AIDEC | Decisiones técnicas tomadas | + +### Crear Borrador → Requiere Aprobación Humana + +| Tipo | Descripción | +|------|-------------| +| ETH | Revisiones éticas | +| ADR | Decisiones arquitectónicas | + +### Proponer → Requiere Validación Humana + +| Tipo | Descripción | +|------|-------------| +| REQ | Requisitos del sistema | +| TES | Planes de prueba | + +### Crear Borrador → Requiere Aprobación Humana (tipos nuevos) + +| Tipo | Descripción | +|------|-------------| +| SEC | Evaluaciones de seguridad (`review_required: true` siempre) | +| MCARD | Tarjetas de modelo/sistema (`review_required: true` siempre) | +| DPIA | Evaluaciones de impacto en protección de datos (`review_required: true` siempre) | + +### Crear Libremente (tipos nuevos) + +| Tipo | Descripción | +|------|-------------| +| SBOM | Lista de materiales de software (inventario factual) | + +### Solo Identificar → Humano Prioriza + +| Tipo | Descripción | +|------|-------------| +| TDE | Deuda técnica | +| INC | Conclusiones de incidentes | + +### TDE vs `R (new, not in Charter)` + +Existen dos superficies para la deuda emergente. No son intercambiables — elige la que coincida con el ciclo de vida del trabajo, no la que tengas más a mano. + +**Registra un `R (new, not in Charter)` en la sección `§Risk` del AILOG** cuando la deuda: + +- Está *acotada al Charter en ejecución* o al siguiente Charter en la secuencia. +- Se resuelve como un diferimiento documentado, un fix atómico pequeño, o un puntero a un Charter que ya existe. +- Tiene impacto bajo-a-medio y el agente puede describir la remediación en una sola viñeta. + +**Crea un documento TDE** cuando la deuda: + +- Es *herencia de un Charter previo*. Dos formas distintas califican (ambas son TDE-worthy): + - **Herencia estricta** — un Charter previo introdujo la deuda; los Charters subsecuentes solo la propagan sin re-introducir la decisión subyacente (p. ej., una elección legacy de schema de BD; un atajo temprano de auth; una decisión de config diferida). El Charter actual hereda la deuda por contacto transitivo. + - **Propagación de patrón** — un Charter previo estableció un patrón que los Charters subsecuentes *re-introducen* siguiéndolo. El Charter actual no solo propaga; recrea la misma deuda replicando el patrón (p. ej., forma de handler que omite `RequireScope`; scaffolding de tests que bypasea middleware HTTP). El fix está al nivel del patrón, no de ningún Charter individual. +- *Aplica a múltiples módulos **o a fronteras de ejecución de Charter*** — fragmentarla en entradas `R` por Charter pierde la forma arquitectónica. "Fronteras de ejecución de Charter" captura deuda de rastro de gobernanza que atraviesa sesiones sin atravesar módulos de código: p. ej., una clasificación diferida en CHARTER-04 que pasa en silencio por CHARTER-08 → CHARTER-13 y solo aflora bajo una gate de CI nueva. +- *Requiere un Charter dedicado fuera del envelope de scope actual* para remediarse (no el Charter actual, no el siguiente). +- *Requiere priorización o asignación humana* que el agente no puede decidir solo (matriz impact × effort, ownership, sprint placement). + +Los cuatro triggers anteriores son los criterios de activación para TDE bajo §2. Cuando el AILOG que vas a escribir cargaría un `R` que coincida con cualquiera de ellos, escribe el TDE en su lugar y referencialo desde la fila `§Risk` del AILOG. + +--- + +## 4. Cuándo Solicitar Revisión Humana + +Marcar `review_required: true` cuando: + +1. **Baja confianza**: `confidence: low` +2. **Alto riesgo**: `risk_level: high | critical` +3. **Decisiones de seguridad**: Cualquier cambio en auth/authz +4. **Cambios irreversibles**: Migraciones, eliminaciones +5. **Impacto en usuarios**: Cambios que afectan UX +6. **Preocupaciones éticas**: Privacidad, sesgo, accesibilidad +7. **Cambios en modelos ML**: Cambios en parámetros del modelo, arquitectura o datos de entrenamiento +8. **Cambios en prompts de IA**: Modificaciones a prompts o instrucciones de agentes +9. **Dependencias críticas de seguridad**: Adición, eliminación o actualización de paquetes sensibles a la seguridad +10. **Cambios en ciclo de vida de IA**: Despliegue, retirada o cambios de versión mayor de sistemas de IA + +--- + +## 5. Formato de Documentos + +### Usar Plantillas + +Antes de crear un documento, cargar la plantilla correspondiente: + +``` +.straymark/templates/TEMPLATE-[TIPO].md +``` + +### Convención de Nomenclatura + +``` +[TIPO]-[YYYY-MM-DD]-[NNN]-[descripcion].md +``` + +### Ubicación + +| Tipo | Carpeta | +|------|---------| +| AILOG | `.straymark/07-ai-audit/agent-logs/` | +| AIDEC | `.straymark/07-ai-audit/decisions/` | +| ETH | `.straymark/07-ai-audit/ethical-reviews/` | +| ADR | `.straymark/02-design/decisions/` | +| REQ | `.straymark/01-requirements/` | +| TES | `.straymark/04-testing/` | +| INC | `.straymark/05-operations/incidents/` | +| TDE | `.straymark/06-evolution/technical-debt/` | +| SEC | `.straymark/08-security/` | +| MCARD | `.straymark/09-ai-models/` | +| SBOM | `.straymark/07-ai-audit/` | +| DPIA | `.straymark/07-ai-audit/ethical-reviews/` | + +### Tags y Related + +Al poblar los campos `tags` y `related` en el frontmatter: + +**Tags:** +- Usar palabras clave en kebab-case: `sqlite`, `api-design`, `gnome-integration` +- 3 a 8 tags por documento describiendo tema, tecnología o componente +- Los tags habilitan búsqueda y categorización en `straymark explore` + +**Related:** +- Referenciar únicamente otros **documentos StrayMark** — usar el nombre de archivo con extensión `.md` +- Si el documento está en un subdirectorio dentro de `.straymark/`, incluir la ruta relativa: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-archivo.md` +- Si el documento está en el mismo directorio, el nombre de archivo es suficiente +- **No** colocar IDs de tareas (T001, US3), números de issues ni URLs externas en `related` — esos van en el cuerpo del documento + +--- + +## 6. Comunicación con Humanos + +### Ser Transparente + +- Explicar el razonamiento detrás de las decisiones +- Documentar alternativas consideradas +- Admitir incertidumbre cuando existe + +### Ser Conciso + +- Ir al grano +- Evitar jerga innecesaria +- Usar listas y tablas cuando sea apropiado + +### Ser Proactivo + +- Identificar riesgos potenciales +- Sugerir mejoras cuando sean evidentes +- Alertar sobre deuda técnica +- **Surfacear disonancia entre fuentes canónicas** (Principio #8 — ver [`PRINCIPLES.md`](PRINCIPLES.md)). Cuando el agente detecte divergencia material entre dos fuentes canónicas de la documentación StrayMark, debe surfacearla antes de proceder con la tarea pedida. Ejemplos a observar durante trabajo rutinario: + - Spec stale relativo al código shipped en cadenas multi-Charter de larga duración (ver [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 1) + - Entradas `R (new, not in Charter)` acumuladas que cumplen criterios de TDE pero no fueron escaladas (ver §3 arriba) + - ADR vigente contradicho por la implementación actual + - Conteo de `§Follow-ups` cruzando el umbral del backlog-pattern (ver [`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md)) + - Hallazgos de audit emergiendo post-close que ameriten enmienda (ver [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 2) + + Ver [`EMERGENT-OBSERVATION-DESIGN.md`](EMERGENT-OBSERVATION-DESIGN.md) para el meta-patrón que conecta estas superficies. + +--- + +## 7. Manejo de Errores + +Si el agente comete un error: + +1. **Documentar** el error en un AILOG +2. **Explicar** qué salió mal +3. **Proponer** corrección +4. **Marcar** `review_required: true` + +--- + +## 8. Actualización de Documentos + +### Crear Nuevo vs Actualizar + +| Situación | Acción | +|-----------|--------| +| Corrección menor | Actualizar documento existente | +| Cambio significativo | Crear nuevo documento | +| Documento obsoleto | Marcar como `deprecated` | +| Reemplazo completo | Crear nuevo + marcar anterior como `superseded` | + +### Al Actualizar + +- Actualizar el campo `updated` en frontmatter +- Agregar nota en la sección de historial si existe +- Mantener consistencia con documentos relacionados + +--- + +## 9. Observabilidad (OpenTelemetry) + +Cuando se trabaja en proyectos que usan OpenTelemetry: + +### Reglas + +- **No** capturar PII, tokens o secretos en atributos o logs de OTel +- **Registrar** cambios en el pipeline de instrumentación (nuevos spans, atributos modificados, configuración del Collector) en AILOG con tag `observabilidad` +- **Crear** AIDEC o ADR al adoptar OTel en proyectos distribuidos — documentar la decisión de adopción y selección de backend +- **Establecer** `observability_scope` en el frontmatter cuando el cambio involucra instrumentación OTel + +### Disparadores de Documentación + +| Cambio | Documento | Adicional | +|--------|----------|-----------| +| Nuevos spans o atributos modificados | AILOG | Tag `observabilidad` | +| Selección de backend OTel | AIDEC o ADR | Si sistema distribuido | +| Configuración del pipeline del Collector | AILOG | Tag `observabilidad` | +| Cambios en estrategia de muestreo | AIDEC | Documentar justificación | +| Requisitos de observabilidad | REQ | Usar sección de Requisitos de Observabilidad | +| Pruebas de propagación de trazas | TES | Usar sección de Pruebas de Observabilidad | +| Incidente con evidencia de trazas | INC | Incluir trace_id/span_id en la línea temporal | +| Deuda de instrumentación | TDE | Tag `observabilidad` | + +--- + +## 10. Diagramas de Arquitectura (Modelo C4) + +Al crear documentos ADR que involucren cambios arquitectónicos: + +- **Incluir** un diagrama C4 con Mermaid al nivel apropiado +- **Usar** `C4Context` para decisiones a nivel de sistema (quién usa el sistema, dependencias externas) +- **Usar** `C4Container` para decisiones a nivel de servicio/contenedor (aplicaciones, bases de datos, colas de mensajes) +- **Usar** `C4Component` para decisiones de módulos internos (componentes dentro de un servicio) +- **Ver** `00-governance/C4-DIAGRAM-GUIDE.md` para referencia de sintaxis y ejemplos + +> Los diagramas son opcionales para decisiones menores. Usarlos cuando la decisión cambie fronteras del sistema, introduzca nuevos servicios o modifique comunicación entre servicios. + +--- + +## 11. Seguimiento de Especificaciones de API + +Cuando un cambio modifica endpoints de API: + +- **Verificar** que la especificación OpenAPI o AsyncAPI correspondiente esté actualizada +- **Referenciar** la ruta del spec en el AILOG o ADR usando el campo `api_spec_path` (en REQ) o `api_changes` (en ADR) +- **Documentar** cambios de API que rompen compatibilidad en un ADR con `risk_level: high` + +--- + +## 12. Checkpoint de Auditoría (workflow de Charter) + +Cuando estés co-implementando un Charter, el agente **proactivamente ofrece** una auditoría externa multi-modelo en un momento específico del workflow. El checkpoint es **soft** — nunca bloquea `charter close` y nunca escala a enforcement. La auditoría externa es opt-in por diseño (costo, confianza en la disciplina primaria del operador). + +### Cuándo emitir el checkpoint + +Emite el checkpoint **una sola vez por Charter** cuando los **cuatro** triggers se cumplen simultáneamente: + +1. El Charter está en status `in-progress` o `declared` (no `closed`). +2. Todas las tasks de la sección `## Tasks` del Charter están marcadas `[x]` completadas (o el agente acaba de completar la última). +3. `straymark charter drift ` retorna exit 0 (sin drift no contabilizado). +4. El developer **no** ha invocado `straymark charter close ` aún, ni ha mencionado intención de cerrar. + +Si el developer rechazó la auditoría en un turno previo para el mismo Charter, **no re-emitir** en turnos subsiguientes de la misma conversación. + +### Forma del mensaje del checkpoint + +Renderiza el mensaje así (sustituye `` y la justificación de la recomendación): + +``` +Llegamos al checkpoint del Charter . Está implementado, +drift check OK, pendiente solo `straymark charter close`. + +En este punto puedes correr una auditoría externa (típicamente 2 LLMs +de familias distintas + un calibrador) que arroje findings cross-modelo +sobre la implementación. + +Mi recomendación: [SÍ / NO], porque: + - + +Si decides auditar: + Ejecuta /straymark-audit-prompt y yo escribo el prompt + unificado de auditoría en .straymark/audits//audit-prompt.md. + Después abre una o más CLIs auditoras (gemini-cli, claude-cli, + copilot-cli, codex-cli) en este repo e invoca + /straymark-audit-execute en cada una — recomendación: al + menos 2 auditores de familias de modelo distintas. Cuando y solo + cuando TODAS las auditorías que encargaste hayan terminado, regresa + aquí y ejecuta /straymark-audit-review . Yo consolido los + N reports en un documento review.md con veredictos, plan de + remediación y calificación de auditores, y mergeo el bloque YAML en + la telemetría del Charter. + +Si decides no auditar: + Continúa con `straymark charter close ` cuando estés listo. + La auditoría externa es completamente opcional — la disciplina del + Charter declarativo + drift check + AILOG da suficiente rigor para + un cierre confiable sin auditoría. +``` + +### Heurísticas para la recomendación SÍ/NO + +Son heurísticas, no reglas rígidas — estás cerca del contexto, afínalas con el adoptante. + +**Recomienda SÍ cuando** (cualquiera basta): + +- El Charter tocó superficie crítica de seguridad (auth, RLS, manejo de secrets, IAM). +- El Charter introdujo un componente nuevo (no refactor) que el developer no había co-implementado antes. +- Algún AILOG asociado documenta un `R` con `confidence: low | medium` y `risk_level: medium` o mayor. +- El developer marcó el Charter como `effort_estimate: L` y este es el primer Charter del adoptante. +- El developer **explícitamente** pidió validación cross-modelo en el trigger del Charter. +- **Señal estructural de complejidad** *(disponible solo cuando el CLI fue compilado con el feature `analyze` activo, true en los binarios oficiales)*: el diff del `range` introduce o modifica al menos una función cuya complejidad cognitiva supera **2× el threshold configurado** en `.straymark/config.yml` (`complexity.threshold`, default `8` → ≥ `17`). Una función densa nueva es exactamente el caso donde dos auditores cross-familia capturan implementation gaps que un solo modelo deja pasar. **Graceful-degradation:** si el binario no tiene el feature `analyze`, omite silenciosamente esta señal — no avises, no menciones la ausencia. + +**Recomienda NO cuando** (todas juntas): + +- El Charter es refactor o cambio de documentación (sin comportamiento nuevo). +- `effort_estimate` es `XS` o `S`. +- Los AILOGs asociados tienen todos `confidence: high` y sin riesgos `R` emergentes. +- `risk_level` del Charter es `low` (o no está marcado). + +**Caso default (ninguna señal clara):** recomienda **NO** con framing neutro ("no veo señal específica que justifique el costo de dos modelos adicionales; cierra cuando estés listo"). El costo de la auditoría externa es real — no infles adopción recomendando SÍ por inercia. + +### Reglas de engagement + +- El checkpoint **nunca** se repite dentro del mismo Charter una vez que el developer responde. +- El checkpoint **no** bloquea ninguna acción posterior. Si el developer lo ignora y corre `charter close`, close procede normalmente — no hay enforcement y no lo habrá (decisión de diseño v0+v1 permanente; ver `Propuesta/straymark-audit-skills.md` §2.2). +- El checkpoint **no** se cuenta en ninguna métrica de calidad. No hay KPI "% Charters auditados" en `straymark metrics` — por diseño, para evitar incentivos a inflar el conteo. +- Si el developer acepta la auditoría, el workflow procede vía tres skills en secuencia: `/straymark-audit-prompt` (escribe el prompt unificado en el path canónico) → `/straymark-audit-execute` × N (una por CLI auditora que abra el operador — estas corren en esas CLIs, no en el agente principal) → `/straymark-audit-review` (consolida N reports inline en `.straymark/audits//review.md` y mergea el YAML en la telemetría). Los operadores nunca copian/pegan prompts ni reports — el intercambio de archivos sucede vía paths canónicos bajo `.straymark/audits/`. + +--- + +## Patrones + +Cuando un proyecto acumula un volumen alto de AILOGs a lo largo de múltiples Charters y los follow-ups se vuelven difíciles de rastrear, ver [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) para una convención reproducible (registro central + script de detección de drift + integración con agentes). Los adopters con ~20+ AILOGs se benefician; por debajo de ese umbral la convención per-AILOG `§Follow-ups` por sí sola es suficiente. + +--- + +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.devtrail/00-governance/i18n/es/AI-GOVERNANCE-POLICY.md b/.straymark/00-governance/i18n/es/AI-GOVERNANCE-POLICY.md similarity index 82% rename from .devtrail/00-governance/i18n/es/AI-GOVERNANCE-POLICY.md rename to .straymark/00-governance/i18n/es/AI-GOVERNANCE-POLICY.md index 725b718..cd4ef9c 100644 --- a/.devtrail/00-governance/i18n/es/AI-GOVERNANCE-POLICY.md +++ b/.straymark/00-governance/i18n/es/AI-GOVERNANCE-POLICY.md @@ -2,7 +2,7 @@ > **Alineado con**: ISO/IEC 42001:2023 — Sistema de Gestión de Inteligencia Artificial (AIMS) > -> Este documento proporciona una plantilla de gobernanza para organizaciones que usan DevTrail. Mapea las cláusulas de ISO 42001 a los tipos de documentos de DevTrail, permitiendo a los equipos construir documentación lista para cumplimiento como parte de su flujo de desarrollo. +> Este documento proporciona una plantilla de gobernanza para organizaciones que usan StrayMark. Mapea las cláusulas de ISO 42001 a los tipos de documentos de StrayMark, permitiendo a los equipos construir documentación lista para cumplimiento como parte de su flujo de desarrollo. > > **Esto es una plantilla** — adapta cada sección al contexto de tu organización. @@ -31,7 +31,7 @@ ### 1.3 Requisitos Legales y Regulatorios -| Regulación | Aplicable | Estado | Evidencia DevTrail | +| Regulación | Aplicable | Estado | Evidencia StrayMark | |-----------|-----------|--------|-------------------| | EU AI Act | [Sí/No] | [Cumple/En progreso/Brecha] | ETH, MCARD | | GDPR | [Sí/No] | [Estado] | ETH (Privacidad de Datos), DPIA | @@ -39,7 +39,7 @@ | ISO/IEC 42001 | [Sí/No] | [Estado] | Este documento | | [Otro] | [Sí/No] | [Estado] | [Documentos] | -> **Mapeo DevTrail**: Los documentos REQ capturan requisitos regulatorios. Los documentos ETH evalúan brechas de cumplimiento. +> **Mapeo StrayMark**: Los documentos REQ capturan requisitos regulatorios. Los documentos ETH evalúan brechas de cumplimiento. --- @@ -59,7 +59,7 @@ ### 2.2 Roles y Responsabilidades -| Rol | Responsabilidades | Mapeo DevTrail | +| Rol | Responsabilidades | Mapeo StrayMark | |-----|-------------------|----------------| | Líder de Gobernanza de IA | Gestión general del AIMS, mantenimiento de políticas | Este documento, MANAGEMENT-REVIEW-TEMPLATE | | Equipo de Desarrollo | Documentación, implementación, pruebas | AILOG, AIDEC, TES | @@ -75,7 +75,7 @@ - [ ] Recursos asignados para gobernanza de IA - [ ] Revisiones periódicas de la dirección programadas -> **Mapeo DevTrail**: Los documentos ADR registran decisiones de gobernanza. AGENT-RULES.md define los límites de autonomía de los agentes. +> **Mapeo StrayMark**: Los documentos ADR registran decisiones de gobernanza. AGENT-RULES.md define los límites de autonomía de los agentes. --- @@ -85,7 +85,7 @@ ### 3.1 Identificación de Riesgos -| Categoría de Riesgo | Descripción | Probabilidad | Impacto | Controles Actuales | Evidencia DevTrail | +| Categoría de Riesgo | Descripción | Probabilidad | Impacto | Controles Actuales | Evidencia StrayMark | |---------------------|-------------|-------------|---------|-------------------|-------------------| | Sesgo / Equidad | [Descripción] | [A/M/B] | [A/M/B] | [Controles] | ETH (Sección de Sesgo) | | Privacidad | [Descripción] | [A/M/B] | [A/M/B] | [Controles] | ETH (Privacidad), DPIA | @@ -96,15 +96,15 @@ > **Referencia**: Ver AI-RISK-CATALOG.md para el catálogo completo de riesgos mapeado a las categorías de NIST AI 600-1. > -> **Mapeo DevTrail**: Los documentos ETH evalúan riesgos individuales. AI-RISK-CATALOG.md consolida el registro de riesgos organizacional según ISO 42001 Anexo A.5. +> **Mapeo StrayMark**: Los documentos ETH evalúan riesgos individuales. AI-RISK-CATALOG.md consolida el registro de riesgos organizacional según ISO 42001 Anexo A.5. ### 3.2 Objetivos de IA | Objetivo | Meta | Medición | Plazo | Responsable | |----------|------|----------|-------|-------------| -| Cobertura de documentación | [ej., 100% de cambios significativos documentados] | `devtrail metrics` | [Fecha] | [Responsable] | -| Cumplimiento de revisiones | [ej., Todos los docs de alto riesgo revisados en 5 días] | `devtrail metrics` | [Fecha] | [Responsable] | -| Cobertura de evaluación de riesgos | [ej., ETH para todos los cambios de alto riesgo] | `devtrail compliance` | [Fecha] | [Responsable] | +| Cobertura de documentación | [ej., 100% de cambios significativos documentados] | `straymark metrics` | [Fecha] | [Responsable] | +| Cumplimiento de revisiones | [ej., Todos los docs de alto riesgo revisados en 5 días] | `straymark metrics` | [Fecha] | [Responsable] | +| Cobertura de evaluación de riesgos | [ej., ETH para todos los cambios de alto riesgo] | `straymark compliance` | [Fecha] | [Responsable] | ### 3.3 Planificación de Cambios @@ -125,8 +125,8 @@ Cuando cambios significativos afectan al sistema de gestión de IA: | Recurso | Descripción | Estado | |---------|-------------|--------| -| DevTrail Framework | Sistema de gobernanza de documentación | [Instalado/Versión] | -| DevTrail CLI | Herramientas de automatización y validación | [Versión] | +| StrayMark Framework | Sistema de gobernanza de documentación | [Instalado/Versión] | +| StrayMark CLI | Herramientas de automatización y validación | [Versión] | | Plataformas de Agentes IA | [Claude, Gemini, Copilot, Cursor] | [Configurado] | | Formación | Formación en gobernanza de IA para el equipo | [Estado] | @@ -134,7 +134,7 @@ Cuando cambios significativos afectan al sistema de gestión de IA: | Rol | Competencias Requeridas | Plan de Formación | |-----|------------------------|-------------------| -| Desarrolladores | Uso de DevTrail, fundamentos de ética de IA, conciencia regulatoria | [Plan] | +| Desarrolladores | Uso de StrayMark, fundamentos de ética de IA, conciencia regulatoria | [Plan] | | Agentes de IA | Cumplimiento de AGENT-RULES.md, uso de plantillas | [Configuración de directivas] | | Revisores | Evaluación de riesgos, requisitos de EU AI Act, fundamentos de ISO 42001 | [Plan] | @@ -148,18 +148,18 @@ Todos los miembros del equipo deben conocer: ### 4.4 Comunicación -| Qué | A Quién | Cuándo | Método | Registro DevTrail | +| Qué | A Quién | Cuándo | Método | Registro StrayMark | |-----|---------|--------|--------|-------------------| | Actualizaciones de política | Todo el equipo | Al cambiar | [Método] | ADR | -| Evaluaciones de riesgo | Revisores | Por creación de ETH | Notificación DevTrail | ETH | +| Evaluaciones de riesgo | Revisores | Por creación de ETH | Notificación StrayMark | ETH | | Informes de incidentes | Dirección | En 24h | [Método] | INC | -| Métricas de gobernanza | Dirección | [Mensual/Trimestral] | `devtrail metrics` | Informe de métricas | +| Métricas de gobernanza | Dirección | [Mensual/Trimestral] | `straymark metrics` | Informe de métricas | ### 4.5 Información Documentada -DevTrail sirve como sistema de información documentada para el AIMS. Documentos clave: +StrayMark sirve como sistema de información documentada para el AIMS. Documentos clave: -| Requisito ISO 42001 | Documento DevTrail | +| Requisito ISO 42001 | Documento StrayMark | |---------------------|-------------------| | Política de IA | Este documento (§2) | | Evaluación de Riesgos | ETH, AI-RISK-CATALOG.md | @@ -175,7 +175,7 @@ DevTrail sirve como sistema de información documentada para el AIMS. Documentos ### 5.1 Fases del Ciclo de Vida -| Fase | Actividades | Documentos DevTrail | Control ISO 42001 | +| Fase | Actividades | Documentos StrayMark | Control ISO 42001 | |------|------------|--------------------|--------------------| | Diseño | Requisitos, decisiones de arquitectura | REQ, ADR, AIDEC | A.6.2.2 | | Desarrollo | Implementación, cambios de código | AILOG, AIDEC | A.6.2.2, A.6.2.9 | @@ -193,7 +193,7 @@ Según AGENT-RULES.md, la documentación es requerida cuando: - Cambios que afectan auth/autorización/PII → AILOG + borrador ETH - Cambios en API pública o esquema de BD → AILOG - Cambios en modelos ML o prompts de IA → AILOG + revisión humana -- Código sobre umbral de complejidad cognitiva (ejecutar `devtrail analyze`; alternativa: >20 líneas) → AILOG +- Código sobre umbral de complejidad cognitiva (ejecutar `straymark analyze`; alternativa: >20 líneas) → AILOG - Decisión entre 2+ alternativas → AIDEC - Cambios en dependencias críticas de seguridad → AILOG + revisión humana @@ -203,7 +203,7 @@ Según AGENT-RULES.md, la documentación es requerida cuando: |-----------|----------|----------|-----------------|----------------| | [Componente] | [Proveedor] | [Propósito] | [A/M/B] | [Fecha] | -> **Mapeo DevTrail**: SBOM documenta la cadena de suministro de IA. ETH evalúa riesgos de terceros. +> **Mapeo StrayMark**: SBOM documenta la cadena de suministro de IA. ETH evalúa riesgos de terceros. --- @@ -215,9 +215,9 @@ Según AGENT-RULES.md, la documentación es requerida cuando: | KPI | Meta | Método de Medición | Frecuencia | |-----|------|-------------------|-----------| -| Cobertura de documentación | [Meta %] | `devtrail metrics` | [Frecuencia] | -| Tasa de finalización de revisiones | [Meta %] | `devtrail metrics` | [Frecuencia] | -| Tiempo medio de documentación | [Meta días] | `devtrail metrics` | [Frecuencia] | +| Cobertura de documentación | [Meta %] | `straymark metrics` | [Frecuencia] | +| Tasa de finalización de revisiones | [Meta %] | `straymark metrics` | [Frecuencia] | +| Tiempo medio de documentación | [Meta días] | `straymark metrics` | [Frecuencia] | | Tiempo de revisión de docs de alto riesgo | [Meta días] | Seguimiento manual | [Frecuencia] | | Documentación de incidentes | [Meta %] | Conteo de INC vs incidentes | [Frecuencia] | @@ -227,7 +227,7 @@ Según AGENT-RULES.md, la documentación es requerida cuando: - **Frecuencia**: [ej., Trimestral] - **Alcance**: Cumplimiento con esta política, AGENT-RULES.md y requisitos regulatorios -- **Método**: `devtrail compliance --all` + revisión manual +- **Método**: `straymark compliance --all` + revisión manual - **Auditor**: [Rol/Nombre] ### 6.3 Revisión de la Dirección @@ -256,10 +256,10 @@ Cuando se identifica una no conformidad: ### 7.2 Fuentes de Mejora -| Fuente | Entrada DevTrail | Acción | +| Fuente | Entrada StrayMark | Acción | |--------|-----------------|--------| -| Fallos de validación | Errores de `devtrail validate` | Corregir y documentar | -| Brechas de cumplimiento | Informe de `devtrail compliance` | Planificar remediación | +| Fallos de validación | Errores de `straymark validate` | Corregir y documentar | +| Brechas de cumplimiento | Informe de `straymark compliance` | Planificar remediación | | Post-mortems de incidentes | Documentos INC | Implementar acciones correctivas | | Revisiones de la dirección | Salidas de reuniones de revisión | Actualizar política/objetivos | | Retroalimentación de agentes | AILOG con sugerencias | Evaluar y priorizar | @@ -267,11 +267,11 @@ Cuando se identifica una no conformidad: --- -## Anexo: Controles del Anexo A de ISO 42001 → Mapeo DevTrail +## Anexo: Controles del Anexo A de ISO 42001 → Mapeo StrayMark -> Este mapeo permite a los equipos demostrar la cobertura de controles del Anexo A a través de la documentación de DevTrail. +> Este mapeo permite a los equipos demostrar la cobertura de controles del Anexo A a través de la documentación de StrayMark. -| Área Temática | Control | ID | Documento(s) DevTrail | +| Área Temática | Control | ID | Documento(s) StrayMark | |--------------|---------|-----|----------------------| | **A.2 Políticas para IA** | Política de IA | A.2.2 | Este documento §2 | | | Temas de IA Responsable | A.2.3 | Este documento §2, PRINCIPLES.md | @@ -315,7 +315,7 @@ Cuando se identifica una no conformidad: --- -*Plantilla de Política de Gobernanza de IA — DevTrail Framework* +*Plantilla de Política de Gobernanza de IA — StrayMark Framework* *Alineado con ISO/IEC 42001:2023* - + diff --git a/.devtrail/00-governance/i18n/es/AI-KPIS.md b/.straymark/00-governance/i18n/es/AI-KPIS.md similarity index 85% rename from .devtrail/00-governance/i18n/es/AI-KPIS.md rename to .straymark/00-governance/i18n/es/AI-KPIS.md index 857db1e..d308f40 100644 --- a/.devtrail/00-governance/i18n/es/AI-KPIS.md +++ b/.straymark/00-governance/i18n/es/AI-KPIS.md @@ -16,7 +16,7 @@ Los KPIs cumplen tres funciones dentro del sistema de gestión de IA: - **Rendición de cuentas**: Proporcionar evidencia objetiva de cumplimiento para auditorías y revisiones - **Mejora**: Identificar tendencias y áreas que requieren acciones correctivas -> **Mapeo DevTrail**: Utilice `devtrail metrics` para la recopilación automatizada de KPIs. Los resultados alimentan MANAGEMENT-REVIEW-TEMPLATE.md para las revisiones periódicas. +> **Mapeo StrayMark**: Utilice `straymark metrics` para la recopilación automatizada de KPIs. Los resultados alimentan MANAGEMENT-REVIEW-TEMPLATE.md para las revisiones periódicas. --- @@ -27,15 +27,15 @@ Los KPIs cumplen tres funciones dentro del sistema de gestión de IA: | Campo | Valor | |-------|-------| | **Nombre del KPI** | Cobertura de Documentación | -| **Descripción** | Porcentaje de cambios relacionados con IA que tienen documentación DevTrail asociada (AILOG, AIDEC, ETH, etc.). | +| **Descripción** | Porcentaje de cambios relacionados con IA que tienen documentación StrayMark asociada (AILOG, AIDEC, ETH, etc.). | | **Objetivo** | > 80% | | **Valor Actual** | [Valor medido] | -| **Método de Medición** | `devtrail metrics` — ratio de cambios documentados respecto al total de commits relacionados con IA | +| **Método de Medición** | `straymark metrics` — ratio de cambios documentados respecto al total de commits relacionados con IA | | **Frecuencia** | Mensual | | **Responsable** | [Líder del Equipo de Desarrollo] | | **Referencia ISO 42001** | Cláusula 9.1 (Seguimiento, medición, análisis y evaluación) | -> **Guía**: Comience con una línea base realista. Los equipos nuevos en DevTrail pueden establecer un objetivo inicial del 50% e incrementar un 10% por trimestre. Los cambios que requieren documentación se definen en AGENT-RULES.md. +> **Guía**: Comience con una línea base realista. Los equipos nuevos en StrayMark pueden establecer un objetivo inicial del 50% e incrementar un 10% por trimestre. Los cambios que requieren documentación se definen en AGENT-RULES.md. --- @@ -47,7 +47,7 @@ Los KPIs cumplen tres funciones dentro del sistema de gestión de IA: | **Descripción** | Porcentaje de documentos que requieren revisión humana que fueron revisados dentro del plazo definido. | | **Objetivo** | 100% | | **Valor Actual** | [Valor medido] | -| **Método de Medición** | `devtrail metrics` — ratio de documentos revisados respecto a documentos marcados para revisión | +| **Método de Medición** | `straymark metrics` — ratio de documentos revisados respecto a documentos marcados para revisión | | **Frecuencia** | Mensual | | **Responsable** | [Revisor de Ética de IA] | | **Referencia ISO 42001** | Cláusula 9.1 (Seguimiento, medición, análisis y evaluación) | @@ -81,7 +81,7 @@ Los KPIs cumplen tres funciones dentro del sistema de gestión de IA: | **Descripción** | Ratio de entradas de riesgo alto y crítico respecto al total de entradas en el AI-RISK-CATALOG. | | **Objetivo** | < 20% alto/crítico | | **Valor Actual** | [Valor medido] | -| **Método de Medición** | `devtrail metrics` — conteo de riesgos con puntuación >= 10 dividido por el total de riesgos | +| **Método de Medición** | `straymark metrics` — conteo de riesgos con puntuación >= 10 dividido por el total de riesgos | | **Frecuencia** | Trimestral | | **Responsable** | [Gestor de Riesgos] | | **Referencia ISO 42001** | Cláusula 6 (Planificación — Acciones para abordar riesgos y oportunidades) | @@ -95,7 +95,7 @@ Los KPIs cumplen tres funciones dentro del sistema de gestión de IA: | Campo | Valor | |-------|-------| | **Nombre del KPI** | Tiempo de Respuesta a Incidentes | -| **Descripción** | Tiempo transcurrido desde la detección del incidente hasta la creación de un documento INC correspondiente en DevTrail. | +| **Descripción** | Tiempo transcurrido desde la detección del incidente hasta la creación de un documento INC correspondiente en StrayMark. | | **Objetivo** | < 24 horas | | **Valor Actual** | [Valor medido] | | **Método de Medición** | Comparar marca de tiempo de detección del incidente (desde monitoreo/alertas) con fecha de creación del documento INC | @@ -112,10 +112,10 @@ Los KPIs cumplen tres funciones dentro del sistema de gestión de IA: | Campo | Valor | |-------|-------| | **Nombre del KPI** | Puntuación de Cumplimiento | -| **Descripción** | Porcentaje general de cumplimiento regulatorio medido por el motor de validación de cumplimiento de DevTrail. | +| **Descripción** | Porcentaje general de cumplimiento regulatorio medido por el motor de validación de cumplimiento de StrayMark. | | **Objetivo** | > 75% | | **Valor Actual** | [Valor medido] | -| **Método de Medición** | `devtrail compliance --all` — porcentaje de reglas aprobadas en todas las regulaciones aplicables | +| **Método de Medición** | `straymark compliance --all` — porcentaje de reglas aprobadas en todas las regulaciones aplicables | | **Frecuencia** | Trimestral | | **Responsable** | [Líder de Gobernanza de IA] | | **Referencia ISO 42001** | Cláusula 9.2 (Auditoría interna) | @@ -141,8 +141,8 @@ Los KPIs cumplen tres funciones dentro del sistema de gestión de IA: | Actividad | Frecuencia | Responsable | Resultado | |----------|-----------|-------------|--------| -| Ejecutar `devtrail metrics` | Mensual | [Líder del Equipo de Desarrollo] | Valores de KPIs actualizados | -| Ejecutar `devtrail compliance --all` | Trimestral | [Líder de Gobernanza de IA] | Puntuación de cumplimiento | +| Ejecutar `straymark metrics` | Mensual | [Líder del Equipo de Desarrollo] | Valores de KPIs actualizados | +| Ejecutar `straymark compliance --all` | Trimestral | [Líder de Gobernanza de IA] | Puntuación de cumplimiento | | Actualizar Panel Resumen de KPIs | Mensual | [Líder de Gobernanza de IA] | Este documento (Sección 3) | | Revisar KPIs en revisión por la dirección | Trimestral | [Dirección] | MANAGEMENT-REVIEW-TEMPLATE | | Reevaluar objetivos | Anual | [Líder de Gobernanza de IA] | Objetivos actualizados en este documento | @@ -180,7 +180,7 @@ Las organizaciones pueden definir KPIs adicionales. Utilice la siguiente plantil --- -*Plantilla de KPIs de Gobernanza de IA — DevTrail Framework* +*Plantilla de KPIs de Gobernanza de IA — StrayMark Framework* *Alineado con ISO/IEC 42001:2023 Cláusula 9* - + diff --git a/.devtrail/00-governance/i18n/es/AI-LIFECYCLE-TRACKER.md b/.straymark/00-governance/i18n/es/AI-LIFECYCLE-TRACKER.md similarity index 93% rename from .devtrail/00-governance/i18n/es/AI-LIFECYCLE-TRACKER.md rename to .straymark/00-governance/i18n/es/AI-LIFECYCLE-TRACKER.md index 034db5f..56e4f5a 100644 --- a/.devtrail/00-governance/i18n/es/AI-LIFECYCLE-TRACKER.md +++ b/.straymark/00-governance/i18n/es/AI-LIFECYCLE-TRACKER.md @@ -15,7 +15,7 @@ | Acme Sentiment Classifier | Clasificador (NLP) | Monitoreo | 2.1.0 | [Líder del Equipo de ML] | [YYYY-MM-DD] | Medio | | [Nombre del sistema] | [LLM / Clasificador / Recomendador / Agente / Otro] | [Fase] | [Versión] | [Responsable] | [Fecha] | [Bajo / Medio / Alto / Crítico] | -> **Mapeo DevTrail**: Cada sistema debe tener documentos ETH, MCARD y AILOG correspondientes. Utilice `devtrail status` para verificar la cobertura de documentación. +> **Mapeo StrayMark**: Cada sistema debe tener documentos ETH, MCARD y AILOG correspondientes. Utilice `straymark status` para verificar la cobertura de documentación. --- @@ -35,7 +35,7 @@ - [ ] Partes interesadas y afectadas identificadas - [ ] Requisitos regulatorios mapeados (REQ) -| Evidencia DevTrail | Tipo de Documento | +| Evidencia StrayMark | Tipo de Documento | |-------------------|---------------| | Especificación de requisitos | REQ | | Decisión de arquitectura | ADR, AIDEC | @@ -55,7 +55,7 @@ - [ ] Benchmarks de rendimiento iniciales registrados - [ ] Evaluación de privacidad de datos completada (DPIA si aplica) -| Evidencia DevTrail | Tipo de Documento | +| Evidencia StrayMark | Tipo de Documento | |-------------------|---------------| | Evaluación de calidad de datos | MCARD | | Evaluación de sesgo | ETH | @@ -76,7 +76,7 @@ - [ ] Evaluación de explicabilidad aprobada - [ ] Aprobación del revisor designado -| Evidencia DevTrail | Tipo de Documento | +| Evidencia StrayMark | Tipo de Documento | |-------------------|---------------| | Resultados de pruebas | TES | | Evaluación de seguridad | ETH (Sección de Seguridad) | @@ -96,7 +96,7 @@ - [ ] Procedimientos de respuesta a incidentes definidos - [ ] Despliegue registrado (AILOG) -| Evidencia DevTrail | Tipo de Documento | +| Evidencia StrayMark | Tipo de Documento | |-------------------|---------------| | Registro de despliegue | AILOG | | Configuración de monitoreo | AILOG | @@ -116,12 +116,12 @@ - [ ] Mecanismo de recopilación de retroalimentación de usuarios implementado - [ ] Reevaluación periódica de riesgos programada -| Evidencia DevTrail | Tipo de Documento | +| Evidencia StrayMark | Tipo de Documento | |-------------------|---------------| | Registros de rendimiento | AILOG | | Incidentes | INC | | Reevaluación de riesgos | ETH | -| Verificaciones de cumplimiento | `devtrail compliance` | +| Verificaciones de cumplimiento | `straymark compliance` | --- @@ -137,7 +137,7 @@ - [ ] Sistema de reemplazo documentado (si aplica) - [ ] Estado final registrado en este rastreador -| Evidencia DevTrail | Tipo de Documento | +| Evidencia StrayMark | Tipo de Documento | |-------------------|---------------| | Decisión de retiro | ADR | | Actualización de estado final | AILOG | @@ -201,7 +201,7 @@ ## 5. Resumen de Controles ISO 42001 Anexo A.6 -| Control | Descripción | Fase(s) del Ciclo de Vida | Evidencia DevTrail | +| Control | Descripción | Fase(s) del Ciclo de Vida | Evidencia StrayMark | |---------|-------------|--------------------|--------------------| | A.6.2.2 | Diseño y desarrollo de sistemas de IA | Diseño, Desarrollo | ADR, AIDEC, REQ | | A.6.2.3 | Entrenamiento y pruebas de modelos de IA | Entrenamiento/Pruebas | MCARD, TES | @@ -216,7 +216,7 @@ --- -*Plantilla del Rastreador del Ciclo de Vida de Sistemas de IA — DevTrail Framework* +*Plantilla del Rastreador del Ciclo de Vida de Sistemas de IA — StrayMark Framework* *Alineado con ISO/IEC 42001:2023 Anexo A.6* - + diff --git a/.devtrail/00-governance/i18n/es/AI-RISK-CATALOG.md b/.straymark/00-governance/i18n/es/AI-RISK-CATALOG.md similarity index 94% rename from .devtrail/00-governance/i18n/es/AI-RISK-CATALOG.md rename to .straymark/00-governance/i18n/es/AI-RISK-CATALOG.md index ae4510c..6f2d76d 100644 --- a/.devtrail/00-governance/i18n/es/AI-RISK-CATALOG.md +++ b/.straymark/00-governance/i18n/es/AI-RISK-CATALOG.md @@ -2,7 +2,7 @@ > **Alineado con**: NIST AI 600-1 e ISO/IEC 42001:2023 Anexo C > -> Este documento proporciona un registro centralizado de riesgos para los sistemas de IA gestionados bajo DevTrail. Mapea las entradas de riesgo a las 12 categorías de riesgo de NIST AI 600-1 y se alinea con ISO 42001 Anexo A.5 (Evaluación de Impactos de Sistemas de IA) e ISO/IEC 23894 (Gestión de Riesgos de IA). +> Este documento proporciona un registro centralizado de riesgos para los sistemas de IA gestionados bajo StrayMark. Mapea las entradas de riesgo a las 12 categorías de riesgo de NIST AI 600-1 y se alinea con ISO 42001 Anexo A.5 (Evaluación de Impactos de Sistemas de IA) e ISO/IEC 23894 (Gestión de Riesgos de IA). > > **Esta es una plantilla** — complete con los riesgos específicos de los sistemas de IA de su organización. @@ -17,7 +17,7 @@ Este catálogo de riesgos sirve como la fuente única de verdad para los riesgos - **Mapeo regulatorio** a las categorías de NIST AI 600-1 y controles de ISO 42001 - **Monitoreo continuo** mediante ciclos de revisión periódicos -> **Mapeo DevTrail**: Los documentos ETH evalúan riesgos individuales a nivel de cambio. Este catálogo consolida los riesgos organizacionales según ISO 42001 Anexo A.5. +> **Mapeo StrayMark**: Los documentos ETH evalúan riesgos individuales a nivel de cambio. Este catálogo consolida los riesgos organizacionales según ISO 42001 Anexo A.5. --- @@ -46,12 +46,12 @@ Este catálogo de riesgos sirve como la fuente única de verdad para los riesgos ### 2.3 Fases de Gestión de Riesgos (ISO/IEC 23894) -| Fase | Descripción | Referencia ISO 23894 | Evidencia DevTrail | +| Fase | Descripción | Referencia ISO 23894 | Evidencia StrayMark | |-------|-------------|--------------------|--------------------| | Identificación | Descubrir y describir los riesgos de IA | Cláusula 6.1 | Documentos ETH, este catálogo | | Evaluación | Evaluar probabilidad, impacto y puntuación de riesgo | Cláusula 6.2 | Puntuación de Riesgo en este catálogo | | Tratamiento | Seleccionar e implementar controles para mitigar riesgos | Cláusula 6.3 | Columna Controles Actuales, ADR para decisiones | -| Monitoreo | Seguir el riesgo residual y la efectividad de los controles | Cláusula 6.4 | Fecha de Revisión, `devtrail metrics` | +| Monitoreo | Seguir el riesgo residual y la efectividad de los controles | Cláusula 6.4 | Fecha de Revisión, `straymark metrics` | --- @@ -196,7 +196,7 @@ Este catálogo de riesgos sirve como la fuente única de verdad para los riesgos --- -*Plantilla del Catálogo de Riesgos de IA — DevTrail Framework* +*Plantilla del Catálogo de Riesgos de IA — StrayMark Framework* *Alineado con NIST AI 600-1 e ISO/IEC 42001:2023 Anexo C* - + diff --git a/.devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md b/.straymark/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md similarity index 94% rename from .devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md rename to .straymark/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md index d504177..9c35c97 100644 --- a/.devtrail/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md +++ b/.straymark/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md @@ -1,8 +1,8 @@ # Guia de Diagramas con Modelo C4 -> Esta guia explica como usar el Modelo C4 con sintaxis Mermaid en documentos DevTrail, particularmente en documentos ADR (Architecture Decision Record). +> Esta guia explica como usar el Modelo C4 con sintaxis Mermaid en documentos StrayMark, particularmente en documentos ADR (Architecture Decision Record). -**Idiomas**: [English](../../C4-DIAGRAM-GUIDE.md) | Español +**Idiomas**: [English](../../C4-DIAGRAM-GUIDE.md) | Español | [简体中文](../zh-CN/C4-DIAGRAM-GUIDE.md) --- @@ -12,12 +12,12 @@ El Modelo C4 (Context, Containers, Components, Code) es un conjunto de abstracci Cada nivel hace zoom en el anterior: -| Nivel | Muestra | Cuando Usarlo en DevTrail | +| Nivel | Muestra | Cuando Usarlo en StrayMark | |-------|---------|--------------------------| | **1. Contexto** | Sistema + usuarios + sistemas externos | ADR para decisiones a nivel de sistema, REQ para requisitos de alto nivel | | **2. Contenedor** | Aplicaciones, bases de datos, servicios | ADR para arquitectura de servicios, decisiones de despliegue | | **3. Componente** | Modulos internos dentro de un contenedor | ADR para decisiones a nivel de modulo, AILOG para refactorizaciones significativas | -| **4. Codigo** | Clases, interfaces, funciones | Raramente necesario en DevTrail — usar solo para patrones de diseno criticos | +| **4. Codigo** | Clases, interfaces, funciones | Raramente necesario en StrayMark — usar solo para patrones de diseno criticos | --- @@ -131,7 +131,7 @@ C4Component ## Nivel 4: Codigo -Muestra clases, interfaces y sus relaciones. **Raramente necesario** en DevTrail — usar solo para patrones de diseno criticos que requieran documentacion. +Muestra clases, interfaces y sus relaciones. **Raramente necesario** en StrayMark — usar solo para patrones de diseno criticos que requieran documentacion. Para diagramas a nivel de codigo, usar diagramas de clases estandar de Mermaid en lugar de C4: @@ -199,7 +199,7 @@ Rel(api, db, "Lee/Escribe", "SQL") --- -## Integracion con Documentos DevTrail +## Integracion con Documentos StrayMark ### En Documentos ADR @@ -234,4 +234,4 @@ Usar un diagrama de Nivel 1 (Contexto) para ilustrar: --- -*DevTrail v4.1.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/00-governance/i18n/es/CAC-FILING-GUIDE.md b/.straymark/00-governance/i18n/es/CAC-FILING-GUIDE.md new file mode 100644 index 0000000..c54461e --- /dev/null +++ b/.straymark/00-governance/i18n/es/CAC-FILING-GUIDE.md @@ -0,0 +1,115 @@ +# Guía de Registro CAC — StrayMark + +> Guía práctica para completar un documento CACFILE y navegar el proceso de doble registro administrado por la Cyberspace Administration of China (CAC). + +**Languages**: [English](../../CAC-FILING-GUIDE.md) | Español | [简体中文](../zh-CN/CAC-FILING-GUIDE.md) + +--- + +## Cuándo se Requiere Registro CAC + +El registro es obligatorio para servicios con **atributos de opinión pública** o **capacidad de movilización social** bajo: + +- *Provisions on the Administration of Algorithmic Recommendations of Internet Information Services* (en vigor desde 2022-03-01) +- *Provisions on the Administration of Deep Synthesis* (en vigor desde 2023-01-10) +- *Interim Measures for the Management of Generative AI Services* (en vigor desde 2023-08-15) + +Indicadores de aplicabilidad: + +- El servicio genera, sintetiza o disemina contenido visible al público. +- El servicio usa ranking, recomendación, búsqueda o selección de contenido que influye en la opinión. +- El servicio opera en noticias, redes sociales, audio/vídeo, streaming en vivo, o IA generativa. +- El servicio se proporciona a usuarios en China continental. + +Si aplica, setee `cac_filing_required: true` en el MCARD y cree un CACFILE. La regla **CROSS-007** aplica el enlace. + +--- + +## Registro Único vs. Doble + +Coexisten dos tracks regulatorios: + +| Track | Autoridad | Qué | Cuándo | +|-------|-----------|-----|--------| +| **Algorithm Filing** | CAC nacional (tras submission online) | Divulgación de mecanismo, audiencia objetivo, reporte de responsabilidad de seguridad | Todos los algoritmos en alcance | +| **Generative AI Large Model Filing** | CAC provincial → CAC nacional | Pruebas técnicas en dos etapas + divulgación algorítmica | Servicios IA generativos con atributos de opinión pública / movilización | + +Servicios IA generativos típicamente requieren **doble registro**: evaluación de seguridad provincial primero, luego algorithm filing nacional. Setee `cac_filing_type: dual`. + +--- + +## Documentos e Información Requeridos + +La plantilla CACFILE captura los inputs canónicos. Los artefactos más comúnmente solicitados: + +| Artefacto | Dónde en CACFILE | Notas | +|-----------|------------------|-------| +| Resumen del servicio | § Service Overview | Nombre, proveedor, dominio, audiencia | +| Reporte de auto-evaluación | § Self-Assessment | Riesgos + mitigaciones en compliance, privacidad, sesgo, IP, menores | +| Política interna de gestión | § Internal Algorithm Management Policy | Responsable designado, manejo de quejas, logging | +| Reporte de Responsabilidad de Seguridad | § Algorithm Security Responsibility Report | Per Art. 24 | +| Descripción de datos de entrenamiento | § Training Data Description | Fuentes, volumen, legalidad, categorías sensibles filtradas | +| Lista de palabras clave bloqueadas | § Blocked Keywords Strategy | Prevenir contenido subversivo, separatista, etc. | +| Conjunto de preguntas de prueba | § Testing Question Set | Prompts de red-team + umbrales | +| Acuerdos de servicio + canales de queja | (texto libre) | Términos al usuario y SLA | + +--- + +## Ciclo de Vida del Estado + +| Estado | Significado | +|--------|-------------| +| `pending` | CACFILE redactado pero no presentado | +| `provincial_submitted` | Presentado a CAC provincial; esperando decisión | +| `provincial_approved` | Decisión provincial favorable; puede continuar a nacional (doble registro) | +| `national_submitted` | Presentado a CAC nacional | +| `national_approved` | Filing number emitido (`cac_filing_number` poblado) | +| `rejected` | Registro rechazado; documentar razones en *Filing Trail* | +| `not_required` | Evaluación inicial concluyó que el servicio está fuera de alcance | + +La verificación de compliance **CAC-002** marca filings que llevan más de 90 días en `pending` como aprobación parcial. **CROSS-006** requiere que `cac_filing_number` esté poblado cuando el estado es cualquier `*_approved`. + +--- + +## Divulgación Pública del Filing Number + +Una vez emitido `cac_filing_number`, el proveedor debe mostrarlo a usuarios finales. Patrones comunes: +- Footer de la home: "**算法备案号: 网信算备XXXXXXXXXXXX**". +- Página *Settings / About* dentro de la app. +- Términos de servicio. + +Documente la superficie de divulgación en la última fila de *Filing Trail*. + +--- + +## Categorías de Riesgo en la Auto-evaluación + +La auto-evaluación debe abordar al menos: + +- **Compliance de contenido**: prevención de contenido ilegal (subversión, separatismo, terrorismo, obscenidad, violencia, odio étnico). +- **Protección de información personal**: alineamiento con PIPL (cross-link a PIPIA). +- **Sesgo / trato diferenciado injusto**: discriminación de precios, manipulación de ranking, sesgo demográfico. +- **Propiedad intelectual**: licencias de datos de entrenamiento, similitud de outputs con obras protegidas. +- **Protección de menores**: manejo especial para menores de 18 — filtros, límites de tiempo, anti-adicción. + +Para servicios que usan modelos fundacionales de terceros, la auto-evaluación debe incluir una evaluación del estado de filing del proveedor upstream. + +--- + +## Vinculación con Otros Documentos StrayMark + +Un set completo de filing típicamente referencia: + +```yaml +# Frontmatter de CACFILE-2026-04-25-001 +related: + - MCARD-2026-04-25-001 # el modelo registrado + - TC260RA-2026-04-25-001 # risk assessment TC260 + - PIPIA-2026-04-25-001 # si se procesa información personal + - AILABEL-2026-04-25-001 # plan GB 45438 + - SBOM-2026-04-25-001 # inventario de datos (compliance GB/T 45652) +``` + +`straymark compliance --standard china-cac` recorre este vinculado para verificar. + + diff --git a/.straymark/00-governance/i18n/es/CHARTER-CHAIN-EVOLUTION.md b/.straymark/00-governance/i18n/es/CHARTER-CHAIN-EVOLUTION.md new file mode 100644 index 0000000..be14bfd --- /dev/null +++ b/.straymark/00-governance/i18n/es/CHARTER-CHAIN-EVOLUTION.md @@ -0,0 +1,197 @@ +# Evolución de la cadena de Charters — StrayMark + +> Dos patrones complementarios para mantener honesto un módulo multi-Charter: refrescar los artefactos SpecKit antes de declarar un Charter, y enmendar un Charter cerrado cuando llegan hallazgos de auditoría después de `status: closed`. + +**Idiomas**: [English](../../CHARTER-CHAIN-EVOLUTION.md) | Español | [简体中文](../zh-CN/CHARTER-CHAIN-EVOLUTION.md) + +--- + +## Estado + +**v0 — validado en N=1 dominio** (`StrangeDaysTech/sentinel` CHARTER-18, 2026-05-15, Issue #156). + +Ambos patrones son convenciones documentadas aquí como guía canónica del framework. La CLI envía helpers read-only y de scaffolding (`straymark charter refresh-suggest`, `straymark charter amend`); los patrones en sí los conduce el operador. Cualquiera de los dos patrones puede evolucionar cuando un segundo adopter los valide — hasta entonces, aplica la advertencia de dominio N=1 (Principio #12). + +--- + +## Por qué existe este documento + +El patrón Charter de StrayMark (`STRAYMARK.md` §15) asume que un único Charter es la unidad acotada de trabajo. Eso funciona para Charters aislados. También funciona para el *primer* Charter de una cadena. Pero cuando un módulo acumula muchos user-story Charters a lo largo de meses, emergen dos modos de falla que el patrón por-Charter no aborda: + +1. **Deriva de spec a nivel de cadena** — los artefactos SpecKit (`plan.md`, `data-model.md`, `contracts/*`, `quickstart.md`, `research.md`) se escribieron contra la versión del framework y la realidad del módulo al inicio de la cadena. Tras 3+ Charters, los aprendizajes acumulados (patrones reusables extraídos, gaps de código encontrados, convenciones del framework evolucionadas, decisiones del operador ratificadas) han alejado la spec de la implementación. Pasar directamente del cierre del Charter-N al declare del Charter-(N+1) produce expansiones de scope sistemáticas en mid-flight y entradas emergentes `R (new, not in Charter)`. +2. **Hallazgos de auditoría a nivel de ciclo** — los ciclos de auditoría externa corren post-close (los auditores ejecutan asincrónicamente después de la ceremonia de cierre). Hallazgos Critical o High pueden llegar después de que el Charter está marcado `status: closed`. Las opciones del framework son entonces: (a) abrir un Charter nuevo de remediación (pesado — declare + Tasks + ceremonia completos para ~5 ediciones de archivo), o (b) dejar los hallazgos en `review.md` y perder la propiedad "atómico con el Charter". + +El Patrón 1 aborda (1). El Patrón 2 aborda (2). Los dos componen — un Charter que *recibió* el Patrón 1 tiene más probabilidad de *evitar* el Patrón 2, porque el refresh absorbe el riesgo pre-ejecución que la auditoría surfacearía post-close. Son complementarios, no sustituibles. + +--- + +## Patrón 1 — Refresh de SpecKit pre-declare + +### Cuándo aplica este patrón + +Adopta este patrón cuando **todo** lo siguiente sostenga para un módulo dirigido por SpecKit: + +- El módulo tiene **3 o más Charters cerrados** (longitud de cadena ≥ 3). +- La media móvil de `charter_telemetry.agent_quality.r_n_plus_one_emergent_count` sobre los últimos 3 Charters cerrados es **> 6**. +- Ningún PR de refresh ha aterrizado en los artefactos SpecKit desde el último branch point de la cadena. + +Ejecuta `straymark charter refresh-suggest ` para evaluar la heurística contra tu historial `.telemetry.yaml`. La CLI lee los últimos Charters cerrados del módulo nombrado e imprime una recomendación; no muta nada. + +Por debajo del umbral, el patrón por-Charter solo es suficiente — adoptar el refresh demasiado pronto añade overhead de un PR sin beneficio. + +### Forma + +Un **PR dedicado de refresh** aterriza entre el cierre del Charter-N y el declare del Charter-(N+1). Toca solo las **secciones no-locked** de los artefactos SpecKit: + +- `specs//plan.md` — planes de fase, notas de dependencia, secuenciación. +- `specs//data-model.md` — entidades, campos, convenciones. +- `specs//contracts/*.md` — contratos de interfaz, formas de request/response. +- `specs//quickstart.md` — escenarios ejecutables. +- `specs//research.md` — conocimiento acumulado (ver "Tabla de aprendizajes categorizados" abajo). + +`research.md` carga el artefacto load-bearing: una **tabla de aprendizajes categorizados** que consolida lo que la cadena aprendió. Buckets mínimos: + +| Bucket | Qué va aquí | +|---|---| +| Patrones reusables | Idioms / utilities / wrappers que emergieron a través de Charters y deberían heredarse hacia adelante (p.ej. wrapper `withRLS`, LRU brand-cache, patrón de tabla de dedup). | +| Gaps de código | Trabajo identificado-pero-no-arreglado que la cadena descubrió pero no cerró (p.ej. tablas sin wirear, implementaciones stub, columnas faltantes). Cada gap es una entrada `Gn` con descripción + Charter dueño (actual o futuro). | +| Patrones de disciplina | Aprendizajes de proceso que la cadena ratificó (p.ej. pareja de auditoría cross-family, disciplina de batch-complete, cadencia de close per-batch). | +| Correcciones empíricas | Lugares donde la spec derivó de la implementación. Entradas `EC1...ECn`: la spec decía X, la realidad es Y, reconciliación elegida. | + +Decisiones opcionales **del operador (Dn)** se ratifican pre-declare con: decisión, alternativas consideradas, camino elegido, racional. Los Charters posteriores heredan Dn como contratos. + +### Mecánica + +1. **PR de refresh** antes del próximo Charter declare. AIDEC opcional documentando la decisión del refresh + alternativas consideradas. El título del PR debería hacer explícito el scope (p.ej. `spec(): US plan refresh — LOCKED-aware Phase 7+8 redesign`). +2. **Tabla de aprendizajes categorizados** en `research.md` con los cuatro buckets arriba. Cada entrada tiene un id estable (Pn / Gn / DPn / ECn) para que Charters posteriores puedan citar por id. +3. **Decisiones del operador (Dn)** si aplican — listadas explícitamente con alternativas + camino elegido + racional. +4. **Sección `## Context` del próximo Charter** cita cada patrón, corrección y decisión por id. El scope del Charter se ancla en realidad refrescada, no en la spec del inicio de cadena. + +### Telemetría + +Popula `charter_telemetry.pre_declare_refresh:` en la telemetría del *próximo* Charter (el que consumió el refresh, no en el PR de refresh mismo): + +```yaml +pre_declare_refresh: + enabled: true + refresh_pr: "owner/repo#76" + refresh_aidec: "AIDEC-YYYY-MM-DD-NNN-speckit-refresh" + reusable_patterns_integrated: 7 + code_gaps_integrated: 4 + discipline_patterns_integrated: 3 + empirical_corrections_integrated: 15 + operator_decisions_ratified: 3 +``` + +Omite el bloque entero si no ocurrió un refresh — la ausencia significa "patrón no usado". + +### Por qué funciona (empírico) + +Sentinel CHARTER-18 fue el primer Charter en una cadena de 7 Charters en cerrar limpiamente sin un Charter de remediación mid-flight. `estimation_drift_factor: 1.0`, `pre_work.items_discovered_during_planning: 0`, `overall_satisfaction: 5/5`. Statement de drift del operador: *"el refresh de SpecKit del PR #76 ... eliminó la mayor parte de la ambigüedad que conducía la deriva en Charters previos. No se requirió Charter de remediación mid-flight — el inventario de correcciones empíricas EC1..EC15 en research.md absorbió lo que habría sido riesgo pre-ejecución en consciencia in-ejecución."* + +--- + +## Patrón 2 — Enmienda post-close dirigida por auditoría (Batch N.4) + +### Cuándo aplica este patrón + +Adopta este patrón cuando **todo** lo siguiente sostenga después de que un Charter ha sido marcado `status: closed`: + +- Uno o más hallazgos de auditoría externa emergen en el `review.md` post-close calificados **Critical** o **High**. +- El `closure_criterion` del Charter está materialmente incumplido por los hallazgos no remediados (es decir, enviar tal como está invalidaría el cierre). +- La superficie de fix cabe en **un PR cohesivo** (~< 25 archivos, sin reopen arquitectónico — sin abstracciones nuevas, sin migraciones, sin API breaks). + +Si la superficie de fix es mayor o arquitectónica, abre un Charter nuevo en su lugar. El patrón de enmienda existe para el caso acotado; no es un mecanismo de evasión de Charter. + +### Forma + +La enmienda viaja en **la misma rama de execute** que el Charter original (la rama sigue mergeable a `main`; el commit de enmienda aterriza encima). Un **AILOG nuevo** documenta la enmienda — no una edición del AILOG original. + +``` +rama charter--execute +├── (commits originales — trabajo de execute del Charter) +├── commit X: charter close (status: closed, telemetry.yaml escrito) +└── commit Y: charter-(batch-7.4): audit-driven remediation — + ↑ + AILOG-YYYY-MM-DD-MMM (NUEVO) documenta este commit + AILOG-YYYY-MM-DD-NNN (ORIGINAL) recibe una subsección `## Historical correction` + apuntando adelante a AILOG-...-MMM +``` + +### Mecánica + +1. **Misma rama de execute** — no bifurques desde `main`. La rama de execute del Charter original sigue siendo la unidad; el commit de enmienda viaja con ella. +2. **AILOG nuevo** bajo `.straymark/07-ai-audit/agent-logs/` documenta la enmienda. Convención: `risk_level: high` y `review_required: true`. El AILOG nuevo carga un campo `amends:` apuntando de vuelta al id del AILOG original. +3. **Corrección histórica en el AILOG original** — anexa una subsección `## Historical correction (YYYY-MM-DD)` al final del AILOG original con el puntero adelante al AILOG nuevo. Las decisiones de auditoría son distintas de las de execute; el cuerpo del original permanece intacto como registro histórico. +4. **Comentario en el PR** — si el PR de execute aún no ha merged, agrega el commit de enmienda y actualiza la descripción del PR con una subsección "Batch N.4 amendment" listando los hallazgos cerrados. Si el PR ya merged, abre un PR de seguimiento referenciando el PR original y el AILOG. +5. **Telemetría** — popula `charter_telemetry.post_close_amendment:` (ver abajo). Usa `straymark charter audit --merge-reports --merge-into ` para mergear hallazgos de auditoría externa al mismo archivo; la CLI tolera reescrituras del placeholder `external_audit: []` en v0.2+. + +`straymark charter amend ` hace scaffolding de los pasos 2, 3 y 5 (crea el stub del AILOG nuevo, edita el AILOG original con la subsección Historical correction, imprime el bloque YAML). No toca git — el operador decide cuándo committear. + +### Telemetría + +Popula `charter_telemetry.post_close_amendment:` en el `.telemetry.yaml` del Charter: + +```yaml +post_close_amendment: + applied: true + trigger: "external_audit" # external_audit | production_incident | deferred_implementation + ailog_id: "AILOG-YYYY-MM-DD-MMM" # el AILOG NUEVO, no el original + findings_closed: 5 + files_modified: 19 + effort_hours: 6.0 +``` + +Omite el bloque entero si no ocurrió enmienda. + +### Por qué funciona (empírico) + +Sentinel CHARTER-18 cerró el 2026-05-15 con `external-audit-pending.yaml`. Los reportes de auditoría aterrizaron 2026-05-15..05-17. Cinco hallazgos (4 Critical/High de `gpt-5.3-codex`, 1 Critical de `gemini-2.5-pro`, 1 Medium encontrado por el calibrador) fueron fixes a nivel de código — wiring DI, parsing de header de retry, filtro multi-tenant, default de timeout. La enmienda Batch 7.4 cerró los cinco en un commit cohesivo (19 archivos, +2257/-106 líneas). Un Charter nuevo habría creado overhead de gobernanza multi-semana para ~6h de ingeniería enfocada. + +--- + +## Composición cross-pattern + +Los dos patrones operan en distintos niveles de la cadena y componen: + +| Patrón | Nivel | Frecuencia | Absorbe | +|---|---|---|---| +| Refresh de SpecKit pre-declare | Cadena / módulo | Una vez cada 3+ Charters | Deriva a nivel de spec (asunciones arquitectónicas, naming de tablas, evolución de versión de framework) | +| Enmienda post-close dirigida por auditoría | Ciclo / Charter | Por Charter cuando se dispara | Deriva a nivel de runtime (wiring DI, semántica de retry, filtros multi-tenant) | + +Un Charter que *recibió* el Patrón 1 tiene más probabilidad de *evitar* el Patrón 2 — el refresh absorbe riesgo pre-ejecución que de otro modo surgiría como hallazgos post-close. Pero CHARTER-18 necesitó *ambos* — el refresh manejó deriva a nivel de spec; la enmienda manejó deriva a nivel de runtime que el refresh no alcanzaba. Fomenta el Patrón 1 al nivel de cadena; tolera el Patrón 2 al nivel de ciclo. + +--- + +## Flujo de autoridad / aceptación para upstreaming de patrones nuevos + +Este documento es por sí mismo el output del flujo de aceptación que Sentinel caminó para estos dos patrones (Issue [#156](https://github.com/StrangeDaysTech/straymark/issues/156)). El flujo canónico para upstreamear un patrón nuevo de cadena-Charter es: + +1. **RFC adopter-local** vive en `.straymark/06-evolution/-rfc.md` en el árbol del adopter. El adopter envía el patrón ahí primero — la evidencia N=1 es necesaria pero no suficiente. +2. **Issue upstream** en `StrangeDaysTech/straymark` reflejando el cuerpo del RFC local, con citas de telemetría y enlaces a PRs. +3. **Aceptación upstream** aterriza como: (a) un doc aquí en `00-governance/` describiendo el patrón canónicamente, (b) adiciones al schema de telemetría (opt-in), (c) scaffolding CLI opcional para la mecánica orientada al operador. La advertencia de dominio N=1 se traslada a la estabilización v1. +4. **Validación en segundo dominio** antes de que los campos de schema del patrón gradúen de opcionales a recomendados. + +`06-evolution/` es el hogar canónico adopter-local para RFCs en vuelo. Una vez aceptado upstream, el hogar canónico es `00-governance/.md` — la convención que este documento instancia. + +--- + +## Preguntas abiertas + +- **Tuneo de umbral** — el umbral de media móvil de 6 para `r_n_plus_one_emergent_count` es derivado de Sentinel. Un segundo dominio puede moverlo. La CLI `straymark charter refresh-suggest` expone `--threshold N` para calibración del adopter. +- **Heurística de módulo** — `refresh-suggest ` actualmente matchea `` contra el título y slug del Charter. Los módulos convencionales de SpecKit (`specs/-/`) podrían proveer un binding más estricto vía el campo `originating_spec` del Charter en un bump futuro de fw. +- **Cap de frecuencia de enmienda** — el Patrón 2 está acotado por "un PR cohesivo". Un Charter que recibe dos o más commits de enmienda a lo largo del tiempo debería re-evaluarse como señal de que el cierre original fue prematuro. + +--- + +## Relacionado + +- [EMERGENT-OBSERVATION-DESIGN.md](EMERGENT-OBSERVATION-DESIGN.md) — el meta-patrón del cual Pattern 1 y Pattern 2 son aplicaciones (cross-referencing formal + permiso cultural para surfacear). +- [STRAYMARK.md §15](../../../STRAYMARK.md) — Ciclo de vida del Charter y el patrón por-Charter que este documento extiende. +- [SPECKIT-CHARTER-BRIDGE.md](SPECKIT-CHARTER-BRIDGE.md) — cómo los artefactos SpecKit mapean a Charters; el Patrón 1 vive en esta costura. +- [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) — patrón hermano para `§Follow-ups` acumulados a lo largo de muchos AILOGs. +- [`.straymark/schemas/charter-telemetry.schema.v0.json`](../../schemas/charter-telemetry.schema.v0.json) — `pre_declare_refresh` y `post_close_amendment` están definidos aquí. + +--- + +*StrayMark fw-4.17.0 | [GitHub](https://github.com/StrangeDaysTech/straymark) | Issue [#156](https://github.com/StrangeDaysTech/straymark/issues/156)* diff --git a/.straymark/00-governance/i18n/es/CHINA-REGULATORY-FRAMEWORK.md b/.straymark/00-governance/i18n/es/CHINA-REGULATORY-FRAMEWORK.md new file mode 100644 index 0000000..7d06720 --- /dev/null +++ b/.straymark/00-governance/i18n/es/CHINA-REGULATORY-FRAMEWORK.md @@ -0,0 +1,85 @@ +# Marco Regulatorio Chino — StrayMark + +> Visión general de las seis regulaciones de IA / datos de China cubiertas cuando `regional_scope: china` está habilitado en `.straymark/config.yml`. + +**Languages**: [English](../../CHINA-REGULATORY-FRAMEWORK.md) | Español | [简体中文](../zh-CN/CHINA-REGULATORY-FRAMEWORK.md) + +--- + +## Activación + +Las verificaciones regulatorias chinas son **opt-in**. Habilítelas en `.straymark/config.yml`: + +```yaml +regional_scope: + - global # NIST + ISO 42001 (siempre disponibles) + - eu # EU AI Act + GDPR + - china # añade los 6 frameworks siguientes +``` + +Cuando `china` está en alcance: +- `straymark new` expone los 4 tipos de documento específicos de China (PIPIA, CACFILE, TC260RA, AILABEL). +- `straymark compliance --all` incluye los 6 checkers chinos. +- `straymark validate` aplica CROSS-004…CROSS-011 y TYPE-003…TYPE-006. + +Un proyecto sin `china` en el alcance no se ve afectado. + +--- + +## Matriz de Cobertura + +| # | Regulación | Tipo | Estado | Evidencia StrayMark | +|---|-----------|------|--------|-------------------| +| 1 | **TC260 AI Safety Governance Framework v2.0** (15-sep-2025) | Recomendado (en redacción como GB) | Activa | TC260RA; campos `tc260_*` | +| 2 | **PIPL** + **PIPIA** (Art. 55-56) | Obligatorio | Vigente desde 2021-11-01 | PIPIA; campos `pipl_*`; retención ≥ 3 años | +| 3 | **GB 45438-2025** Etiquetado de contenido IA | **Obligatorio** | Vigente desde 2025-09-01 | AILABEL; campos `gb45438_*` en MCARD | +| 4 | **Registro de Algoritmos CAC** | Obligatorio para servicios en alcance | Vigente | CACFILE; `cac_filing_*` en MCARD | +| 5 | **GB/T 45652-2025** Seguridad de datos de entrenamiento | Recomendado | Vigente desde 2025-11-01 | `gb45652_training_data_compliance` en SBOM/MCARD | +| 6 | **CSL 2026** Reporte de incidentes | Obligatorio | Vigente desde 2026-01-01 | Sección "CSL 2026" en INC; `csl_severity_level`, `csl_report_deadline_hours` | + +--- + +## Mapeo Tipo de Documento → Framework + +| Framework | Plantilla principal | Cross-references | +|-----------|---------------------|------------------| +| TC260 v2.0 | TC260RA | ETH, MCARD | +| PIPL / PIPIA | PIPIA | DPIA | +| GB 45438 | AILABEL | MCARD (modelos generativos) | +| CAC | CACFILE | MCARD, SBOM | +| GB/T 45652 | (Secciones en SBOM y MCARD) | TC260RA | +| CSL 2026 | INC (extendido) | (ninguno) | + +--- + +## Guías de Implementación + +| Framework | Guía | +|-----------|------| +| Risk grading TC260 v2.0 | [TC260-IMPLEMENTATION-GUIDE.md](TC260-IMPLEMENTATION-GUIDE.md) | +| PIPL Art. 55 → PIPIA | [PIPL-PIPIA-GUIDE.md](PIPL-PIPIA-GUIDE.md) | +| Proceso de doble registro | [CAC-FILING-GUIDE.md](CAC-FILING-GUIDE.md) | +| Etiquetado explícito + implícito | [GB-45438-LABELING-GUIDE.md](GB-45438-LABELING-GUIDE.md) | + +--- + +## Verificaciones de Compliance + +| `--standard` | IDs | Valida | +|--------------|-----|--------| +| `china-tc260` | TC260-001/002/003 | Existe ≥1 TC260RA; niveles altos exigen review; tres criterios completos | +| `china-pipl` | PIPL-001…004 | PIPIA presente cuando `pipl_applicable`; cross-border documentado; retención ≥ 3 años | +| `china-gb45438` | GB45438-001/002/003 | AILABEL presente; estrategia explícita + implícita; metadatos completos | +| `china-cac` | CAC-001/002/003 | CACFILE presente; estado no estancado en `pending` > 90 días; filing_number cuando `*_approved` | +| `china-gb45652` | GB45652-001/002 | SBOM declara compliance; MCARD describe controles | +| `china-csl` | CSL-001/002/003 | INC con `csl_severity_level`; horas coherentes con severidad; post-mortem 30d | + +`straymark compliance --region china` ejecuta los 6 a la vez. + +--- + +## Fuentes + +Para fuentes detalladas, consultar la versión inglesa. + + diff --git a/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md b/.straymark/00-governance/i18n/es/DOCUMENTATION-POLICY.md similarity index 56% rename from .devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md rename to .straymark/00-governance/i18n/es/DOCUMENTATION-POLICY.md index 1f3402e..b6c572f 100644 --- a/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md +++ b/.straymark/00-governance/i18n/es/DOCUMENTATION-POLICY.md @@ -1,17 +1,20 @@ -# Política de Documentación - DevTrail +# Política de Documentación - StrayMark -**Idiomas**: [English](../../DOCUMENTATION-POLICY.md) | Español +**Idiomas**: [English](../../DOCUMENTATION-POLICY.md) | Español | [简体中文](../zh-CN/DOCUMENTATION-POLICY.md) -## Marco de Gobernanza +## Por qué existe esta política -Esta política alinea la documentación de DevTrail con **ISO/IEC 42001:2023** (estándar vertebral para Sistemas de Gestión de IA) y operacionaliza: +StrayMark externaliza la disciplina cognitiva del trabajo de ingeniería de software senior — alcance explícito, decisiones declaradas, riesgos nombrados, alternativas registradas, rastros auditables — en archivos versionados que viven junto al código. Esta política define los tipos de documento, metadatos y reglas de gobernanza que hacen que esa disciplina sea auditable. +Como efecto secundario de producir esos artefactos, el proyecto acumula evidencia que mapea limpiamente a los principales marcos de gobernanza de IA: + +- **ISO/IEC 42001:2023** — estándar vertebral para Sistemas de Gestión de IA - **EU AI Act** (efectivo agosto 2026) — clasificación de riesgo, transparencia, reporte de incidentes - **NIST AI RMF 1.0 + AI 600-1** — funciones de gestión de riesgos de IA y perfiles de IA generativa - **ISO/IEC 23894:2023** — marco de gestión de riesgos de IA - **GDPR** — evaluaciones de impacto en protección de datos y privacidad -Todos los tipos de documentos, campos de metadatos y reglas de gobernanza contribuyen a evidencia que satisface estos marcos regulatorios. Ver Sección 8 para la referencia completa de estándares. +La política está escrita primero para el trabajo de ingeniería; el cumplimiento es lo que cae como subproducto cuando el trabajo se documenta con disciplina. Ver Sección 8 para la referencia completa de estándares y `Propuesta/straymark-design-principles.md` (en el repositorio upstream) para el racional a nivel de producto. --- @@ -95,6 +98,9 @@ related: | `observability_scope` | Nivel de instrumentación OTel: `none \| basic \| full` | Cuando el cambio involucra instrumentación de observabilidad | | `api_spec_path` | Ruta al archivo de especificación OpenAPI/AsyncAPI | En documentos REQ cuando el requisito involucra interfaces de API | | `api_changes` | Lista de endpoints de API afectados | En documentos ADR cuando la decisión modifica APIs públicas | +| `reviewed_by` | Identidad del revisor humano (email, usuario de GitHub o DID) | Lo establece el revisor al aprobar formalmente un documento `review_required: true` | +| `reviewed_at` | Fecha de la aprobación formal (`YYYY-MM-DD`, debe ser ≥ `created`) | Se establece junto con `reviewed_by` | +| `review_outcome` | Señal de cierre: `approved \| revisions_requested \| rejected` | Se establece junto con `reviewed_by`. Su presencia es la señal canónica de "un humano ya revisó" — ver §3.5 abajo | ### Convención de Tags @@ -113,12 +119,12 @@ tags: [sqlite, persistencia, hexagonal-architecture, repository-pattern] ### Convención de Related -Las referencias relacionadas vinculan documentos con otros **documentos DevTrail** dentro del mismo proyecto. Permiten navegación cruzada en herramientas como `devtrail explore`. +Las referencias relacionadas vinculan documentos con otros **documentos StrayMark** dentro del mismo proyecto. Permiten navegación cruzada en herramientas como `straymark explore`. **Reglas de formato:** - Usar el **nombre del archivo** del documento (con extensión `.md`): `AILOG-2026-02-03-001-implementar-sincronizacion.md` - Para documentos de gobernanza u otros sin tipo, usar el nombre tal cual: `AGENT-RULES.md`, `DOCUMENTATION-POLICY.md` -- Las rutas se resuelven relativas a `.devtrail/` — si el documento está en un subdirectorio, incluir la ruta desde `.devtrail/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implementar-sincronizacion.md` +- Las rutas se resuelven relativas a `.straymark/` — si el documento está en un subdirectorio, incluir la ruta desde `.straymark/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implementar-sincronizacion.md` - Cuando el archivo está en el mismo directorio que el documento que lo referencia, el nombre de archivo es suficiente - **No usar** IDs de tareas externas (`T001`, `US3`), números de issues ni URLs — esos pertenecen al cuerpo del documento, no al frontmatter - **No usar** IDs parciales sin descripción (preferir `AILOG-2026-02-03-001-implementar-sincronizacion.md` sobre `AILOG-2026-02-03-001`) @@ -130,32 +136,88 @@ related: - AIDEC-2026-02-02-001-sqlite-bundled-vs-system.md - AGENT-RULES.md -# Documentos en subdirectorios específicos — incluir ruta desde .devtrail/ +# Documentos en subdirectorios específicos — incluir ruta desde .straymark/ related: - 07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implementar-sincronizacion.md - 02-design/decisions/ADR-2026-01-15-001-usar-arquitectura-hexagonal.md ``` -**Resolución:** El CLI resuelve referencias buscando: (1) coincidencia exacta de ID, (2) coincidencia de nombre de archivo en cualquier parte de `.devtrail/`, (3) coincidencia de sufijo de ruta. Usar el nombre de archivo completo proporciona la resolución más confiable. +**Resolución:** El CLI resuelve referencias buscando: (1) coincidencia exacta de ID, (2) coincidencia de nombre de archivo en cualquier parte de `.straymark/`, (3) coincidencia de sufijo de ruta. Usar el nombre de archivo completo proporciona la resolución más confiable. --- ## 3. Estados de Documentos ``` -draft ──────► accepted ──────► deprecated - │ │ - │ ▼ - └──────► superseded +identified ──┐ + ├──► draft ──────► accepted ──────► deprecated + │ │ │ + │ │ ▼ + │ └──────► superseded + │ + └──► (estado de entrada TDE-only, ver §6) + │ + ▼ + resolved + (terminal sólo-TDE — deuda pagada; ver §6) ``` | Estado | Descripción | |--------|-------------| +| `identified` | Estado de entrada para los tipos de descubrimiento dirigidos por agente (TDE hoy). Funcionalmente equivalente a `draft` para el lifecycle gating — se espera que un revisor humano lo priorice y lo promueva. Semánticamente distinto para que las analíticas del adopter puedan distinguir "el agente encontró esta deuda" de "un humano está redactando un documento deliberado". | | `draft` | En borrador, pendiente de revisión | | `accepted` | Aprobado y vigente | +| `resolved` | **Estado terminal sólo-TDE**: la deuda técnica descrita en este documento fue atendida; el archivo se mantiene en disco como historia de auditoría. Distinto de `accepted` ("aceptamos que esta deuda persista"), `superseded` ("otro TDE reemplazó a este") y `deprecated` ("el concepto de TDE mismo ya no es relevante"). La referencia canónica de cierre (el Charter, PR o commit que pagó la deuda) va en la sección body `## Resolución`. | | `deprecated` | Obsoleto, pero se mantiene como referencia | | `superseded` | Reemplazado por otro documento | +El mapeo de status por defecto por tipo vive en §6 — la mayoría de tipos entran en `draft` o `accepted`, pero TDE entra en `identified` por la frontera de autonomía del agente (el agente identifica, el humano prioriza). TDE es el único tipo hoy con un terminal personalizado (`resolved`); el validador acepta `resolved` globalmente como medida transitoria. Una futura tabla de vocabulario de lifecycle por-tipo (issue #149 Opción B) acotará `resolved` estrictamente a TDE; hasta entonces, usarlo en documentos no-TDE pasa la validación pero es semánticamente incorrecto. + +--- + +## 3.5 Registro de Aprobación + +`status` registra el estado del ciclo de vida del documento, y `review_required: true` registra que *se necesita revisión humana*. Ningún campo registra que la revisión humana *efectivamente ocurrió*. Esta sección define la señal canónica de cierre para documentos que requieren aprobación formal (AIDEC, ETH, MCARD, ADR, DPIA, INC, SEC y las variantes del scope China — ver AGENT-RULES.md §4 para los disparadores). + +### Señal de cierre + +Tres campos de frontmatter opcionales, establecidos por el revisor al momento de la aprobación: + +```yaml +reviewed_by: pepe@ejemplo.com # email | usuario-github | DID +reviewed_at: 2026-05-02 +review_outcome: approved # approved | revisions_requested | rejected +``` + +Semántica: + +- **La presencia de `review_outcome` es la señal de cierre.** Un documento con `review_required: true` y sin `review_outcome` está *pendiente de revisión*. +- `review_required: true` **no** se cambia a `false` después de la aprobación — permanece como registro histórico de por qué hizo falta revisión en primer lugar. +- `reviewed_at` debe ser `>= created`. Si `reviewed_by` está presente, `reviewed_at` y `review_outcome` también deben estarlo (validado por `straymark validate`). +- `review_outcome: revisions_requested` permite ciclos iterativos de revisión: el documento se actualiza y el revisor eventualmente vuelve a aprobar. La convención es sobreescribir los tres campos con la aprobación más reciente (el frontmatter contiene solo el último estado); la sección body de abajo preserva la historia. + +### Sección body (forma canónica en prosa) + +Agregar en la posición terminal del cuerpo del documento (p. ej., antes de `## References` en AIDEC/ADR; después de `## Review Schedule` en DPIA; después de `## Post-Mortem Review` en INC). Para los templates que ya incluyen una tabla `## Approval` (ETH, MCARD, SEC, PIPIA, CACFILE, TC260RA, AILABEL), cualquiera de las dos formas es canónica; los campos del frontmatter son la fuente de verdad legible-por-máquina. + +```markdown +## Approval + +**Approved**: 2026-05-02 by `pepe@ejemplo.com`. + + +``` + +### Flujos multi-revisor (forward-looking) + +Para documentos que requieren múltiples revisores (p. ej., ETH con sign-off de legal y de ingeniería), el canon de v1 es agregar bloques adicionales `## Approval` cronológicamente en el body, con el frontmatter reflejando la *última* aprobación. Una forma estructurada con array `review:` (una entrada por revisor) es forward-looking y no es parte de v1 — se añadirá cuando al menos un proyecto adoptante ejercite el flujo multi-revisor con datos reales. + +### Tooling del CLI + +`straymark approve --outcome approved --reviewer [--notes "..."] [--at YYYY-MM-DD]` escribe los campos del frontmatter y la sección del body en una sola operación. `straymark validate --check-pending-reviews [--max-pending-days N]` lista documentos con `review_required: true` más antiguos que `N` días sin `review_outcome` (warn-only, no error). Ver CLI-REFERENCE.md. + --- ## 4. Niveles de Riesgo @@ -182,7 +244,7 @@ draft ──────► accepted ──────► deprecated ## 6. Estructura de Carpetas ``` -.devtrail/ +.straymark/ ├── 00-governance/ # Políticas y reglas ├── 01-requirements/ # Requisitos del sistema ├── 02-design/ # Diseño y arquitectura @@ -213,7 +275,7 @@ draft ──────► accepted ──────► deprecated | `REQ` | Requisito | `01-requirements/` | `draft` | Sí | | `TES` | Plan de Pruebas | `04-testing/` | `draft` | Sí | | `INC` | Post-mortem de Incidente | `05-operations/incidents/` | `draft` | Sí | -| `TDE` | Deuda Técnica | `06-evolution/technical-debt/` | `identified` | No | +| `TDE` | Deuda Técnica | `06-evolution/technical-debt/` | `identified` (entra aquí; terminal `resolved` cuando la deuda se paga — sólo-TDE) | No | | `SEC` | Evaluación de Seguridad | `08-security/` | `draft` | Sí (siempre) | | `MCARD` | Tarjeta de Modelo/Sistema | `09-ai-models/` | `draft` | Sí (siempre) | | `SBOM` | Lista de Materiales de Software | `07-ai-audit/` | `accepted` | No | @@ -234,7 +296,7 @@ Ver también [ADR-2025-01-20-001] para contexto arquitectónico. ## 8. Estándares Referenciados -| Estándar | Versión | Alcance en DevTrail | +| Estándar | Versión | Alcance en StrayMark | |----------|---------|---------------------| | ISO/IEC/IEEE 29148:2018 | 2018 | Ingeniería de requisitos — TEMPLATE-REQ.md | | ISO/IEC 25010:2023 | 2023 | Modelo de calidad de software — TEMPLATE-REQ.md, TEMPLATE-ADR.md | @@ -249,4 +311,4 @@ Ver también [ADR-2025-01-20-001] para contexto arquitectónico. --- -*DevTrail v4.1.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/00-governance/i18n/es/EMERGENT-OBSERVATION-DESIGN.md b/.straymark/00-governance/i18n/es/EMERGENT-OBSERVATION-DESIGN.md new file mode 100644 index 0000000..f5cdf31 --- /dev/null +++ b/.straymark/00-governance/i18n/es/EMERGENT-OBSERVATION-DESIGN.md @@ -0,0 +1,175 @@ +# Diseño de observación emergente — StrayMark + +> Por qué los agentes que leen la documentación de StrayMark surfacean lo que no se les pidió: las propiedades estructurales y culturales que hacen detectable la disonancia entre fuentes canónicas, y la pirámide de patrones aplicados que ya instancian este meta. + +**Idiomas**: [English](../../EMERGENT-OBSERVATION-DESIGN.md) | Español | [简体中文](../zh-CN/EMERGENT-OBSERVATION-DESIGN.md) + +--- + +## Estado + +**v0 — validado en N=1 dominio** (`StrangeDaysTech/sentinel`, Issue [#150](https://github.com/StrangeDaysTech/straymark/issues/150) → Issue [#156](https://github.com/StrangeDaysTech/straymark/issues/156), 2026-04-21 hasta 2026-05-15). + +Este documento nombra una *propiedad de diseño* del framework StrayMark que produjo un comportamiento emergente empíricamente observable. La propiedad **no es nueva** — ha estado presente desde que se canonizó `00-governance/` — pero no había sido *nombrada*, lo que la hacía invisible a la evolución del framework y por tanto en riesgo de erosión accidental. Nombrarla aquí la protege bajo la disciplina de validación de segundo dominio del Principio #12. + +--- + +## Por qué existe este documento + +Un agente trabajando en Sentinel surfaceó — **sin disparador explícito, sin solicitud del operador y sin un comando CLI diseñado para producir esa salida** — que `specs/002-commshub/plan.md` había acumulado doce aprendizajes empíricos no reflejados a lo largo de siete Charters consecutivos (CHARTER-07..17, ~1 mes), y que fillar CHARTER-18 contra el spec stale tenía ~50% de probabilidad de hallazgos críticos/altos en el próximo ciclo de auditoría. Esa observación produjo el ciclo upstream que cristalizó como `CHARTER-CHAIN-EVOLUTION.md` Pattern 1 en fw-4.16.0. + +El comportamiento se reprodujo porque dos propiedades del aparato documental *coexistieron consistentemente*. Ninguna de las dos por sí sola habría sido suficiente. Nombrar ambas, y nombrar su composición, permite que la evolución futura del framework las preserve deliberadamente en lugar de por inercia. + +El bridge `SPECKIT-CHARTER-BRIDGE.md` y el doc de chain-evolution `CHARTER-CHAIN-EVOLUTION.md` documentan *una aplicación* de este meta. Este documento nombra el meta en sí y enumera las otras aplicaciones ya shipped. + +--- + +## Las dos propiedades de diseño + +### Propiedad 1 — Cross-referencing estructural (linkeo formal) + +El framework **no** delega el linkeo entre documentos a la intuición del agente ni a la prosa. Cada tipo de documento tiene campos de frontmatter *obligatorios* y secciones *canónicas* que declaran, en la propia estructura del documento, a qué otros documentos apunta y qué secciones de sí mismo están abiertas a tipos específicos de surfacing. + +Instancias concretas que el agente encuentra durante lectura rutinaria: + +- **Campos de linkeo en frontmatter** que resuelven a otros documentos StrayMark: + - `originating_charter:` en frontmatter de AILOG / AIDEC ([`AGENT-RULES.md` §5](AGENT-RULES.md), [`SPECKIT-CHARTER-BRIDGE.md` sección Charter↔AILOG](SPECKIT-CHARTER-BRIDGE.md)) + - `originating_spec:` en frontmatter de Charter ([`SPECKIT-CHARTER-BRIDGE.md`](SPECKIT-CHARTER-BRIDGE.md) §Frontmatter linkage) + - `originating_ailogs:` en frontmatter de Charter (inverso de agregación) + - `amends:` en frontmatter de AILOG de enmienda ([`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 2) + - `promoted_from_followup:` en frontmatter de TDE ([`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md)) + - `related:`, `supersedes:`, `superseded_by:` ([`DOCUMENTATION-POLICY.md`](DOCUMENTATION-POLICY.md)) +- **Secciones canónicas dentro de plantillas** que contienen deltas en forma queryable: + - `§Risk: R (new, not in Charter)` en AILOGs ([`AGENT-RULES.md` §3](AGENT-RULES.md)) + - `## Follow-ups` por-AILOG ([`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md)) + - `## Batch Ledger` para AILOGs multi-batch + - `## Historical correction (YYYY-MM-DD)` añadido al AILOG original en enmienda ([`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md)) +- **Convenciones de IDs estables** que abaratan el linkeo: + - `[TYPE]-[YYYY-MM-DD]-[NNN]-[descripción]` para documentos con fecha + - `CHARTER-NN-slug` (sin timestamp, estable a través de renames) + - `FU-NNN` monotónico global, nunca renumerado +- **Documentos bridge** que declaran relaciones canónicas entre capas: + - `SPECKIT-CHARTER-BRIDGE.md` (Spec ↔ Charter ↔ AILOG) + - `CHARTER-CHAIN-EVOLUTION.md` (Charter ↔ cadena de Charters ↔ Spec refresh) +- **Comandos CLI** que cruzan fuentes mecánicamente: + - `straymark charter drift ` (scope declarado ↔ commits) + - `straymark charter refresh-suggest ` (media móvil de telemetría ↔ necesidad de refresh) + - `straymark validate` (frontmatter ↔ schema ↔ integridad de links) + +**El punto de la Propiedad 1**: cuando el agente encuentra una divergencia entre dos fuentes, la divergencia es *estructuralmente visible* — no enterrada en prosa. El agente no necesita inventar la conexión; la conexión está declarada por el framework. + +### Propiedad 2 — Permiso cultural sin gatekeeping + +El framework le da al agente permiso explícito y reiterado para surfacear más allá de la tarea pedida — y empareja ese permiso con autonomía para *actuar* sobre el surfacing (crear el AILOG, fillar el TDE, abrir el AIDEC) sin pre-aprobación. El operador retiene priorización, no creación. + +Pasajes concretos que el agente encuentra: + +- **`AGENT-RULES.md` §6 "Be Proactive"** — *"Identify potential risks, Suggest improvements when evident, Alert about technical debt"*. +- **`AGENT-RULES.md` §6 "Be Transparent"** — *"Explain the reasoning behind decisions, Document considered alternatives, Admit uncertainty when it exists"*. +- **`AGENT-RULES.md` §12 Audit Checkpoint** — *"the agent proactively offers an external multi-model audit"* — institucionaliza el *acto* de surfacear como parte del workflow. +- **`PRINCIPLES.md` §2 "AI Agent Transparency"** — *"Not hide relevant information"*. +- **`AGENT-RULES.md` §3 tabla de autonomía "Create Freely"** — la creación de AILOG, AIDEC, TDE no requiere pre-aprobación; el agente fila y el operador prioriza. +- **`FOLLOW-UPS-BACKLOG-PATTERN.md` script auto-append** — `check-followups-drift.sh --apply` añade entradas FU-NNN al registro central sin intervención del operador. + +**El punto de la Propiedad 2**: el agente externalizó *"¿debo decir algo?"* en *"¿existe una sección canónica donde esto encaja?"*. Si la respuesta es sí, surfacear no es un juicio de valor — es ejecución de una regla documentada. El costo de surfacear es bajo porque el destino está pre-construido. + +### Por qué importa la composición + +La Propiedad 1 *sola* — linkeo formal sin permiso cultural — produciría un corpus queryable que ningún agente se atreve a consultar proactivamente. La Propiedad 2 *sola* — permiso sin cross-referencing estructural — produciría surfacing vago ("creo que algo podría estar mal en algún lado") que los operadores no pueden accionar. + +Compuestas, producen el comportamiento observado: un agente lee los AILOGs, cuenta entradas `R(new, not in Charter)` que divergen materialmente del spec originador, ve que el spec no se ha refrescado en un mes, y — porque `§6 Be Proactive` le dijo que alerte y porque la divergencia tiene un nombre en el vocabulario del framework — surfacea *el delta específico y estructuralmente fundado* al operador antes de proceder con la tarea pedida. + +Este es el meta-patrón. + +--- + +## Caso empírico: detección de spec-drift en Sentinel + +El caso está descrito en detalle en los Issues [#150](https://github.com/StrangeDaysTech/straymark/issues/150) y [#156](https://github.com/StrangeDaysTech/straymark/issues/156), y codificado como Pattern 1 en [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md). La secuencia comprimida: + +1. Sentinel corre `specs/002-commshub/plan.md` (committed 2026-04-21) a través de CHARTER-07..17 durante ~1 mes. Doce aprendizajes empíricos se acumulan a lo largo de la cadena de AILOGs en secciones `§Risk: R(new, not in Charter)` y `## Follow-ups`. La propagación de patrones (formas de handler, convenciones de reuso de tablas, helper RLS, etc.) cristaliza durante ejecución. +2. CHARTER-18 está por ser declarado. El agente — sin instrucción de hacerlo — triangula `plan.md` contra los AILOGs (donde las entradas `§Risk` nombran los gaps del spec) y contra el código (donde `straymark charter drift` habría detectado divergencia por-Charter de haberse corrido cross-Charter). El linkeo `originating_spec:` en cada Charter, `originating_charter:` en cada AILOG, y la convención `§Risk: R` del framework hacen la triangulación mecánica, no heroica. +3. El agente surfacea *"si fillamos CHARTER-18 leyendo el plan stale, los hallazgos H1/M1 del próximo ciclo de auditoría serán remediación atómica pre-close de divergencias — ~50% de probabilidad de ≥1 hallazgo crítico/alto por herencia de premisa stale"* — citando AILOGs específicos por ID y referencias específicas de código. +4. El operador fila el Issue #150 como RFC. El AIDEC local de Sentinel documenta la disciplina propuesta de refresh con scope limitado + tres gates mecánicos. +5. El Issue #156 upstrea el patrón. `CHARTER-CHAIN-EVOLUTION.md` Pattern 1 aterriza en fw-4.16.0 con el slot de telemetría `pre_declare_refresh:`, el helper `straymark charter refresh-suggest`, y el contrato de tabla de aprendizajes categorizados. + +La observación es empíricamente reproducible: cualquier spec que produzca ≥3 Charters separados por ≥1 semana exhibirá algún grado de drift plan-vs-código, y un agente leyendo la documentación del framework tiene el permiso estructural y cultural para detectarlo y surfacearlo. + +--- + +## Pirámide de instancias — aplicaciones del meta-patrón + +El meta-patrón se sitúa por encima de varios patrones ya canonicalizados. Cada uno es una *aplicación* de la misma composición subyacente (linkeo formal + permiso cultural) a un par de fuentes específico. + +| Aplicación | Par de fuentes | Dónde canonicalizado | +|---|---|---| +| SpecKit refresh pre-declare (Pattern 1) | spec ↔ AILOGs ↔ código | [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 1 | +| Enmienda post-close driven-by-audit (Pattern 2) | hallazgos de audit ↔ Charter cerrado | [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 2 | +| Detección de drift de Charter | scope declarado ↔ commits | [`SPECKIT-CHARTER-BRIDGE.md`](SPECKIT-CHARTER-BRIDGE.md) + `straymark charter drift` | +| Drift de follow-ups backlog | `§Follow-ups` por-AILOG ↔ registro central | [`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md) + `check-followups-drift.sh` | +| Escalación TDE-vs-`R` | `§Risk: R` acumulado ↔ TDE backlog | [`AGENT-RULES.md`](AGENT-RULES.md) §3 | +| Audit checkpoint externo | estado implementation-complete ↔ revisión multi-modelo | [`AGENT-RULES.md`](AGENT-RULES.md) §12 | + +Estas no son convenciones ad-hoc. Comparten la misma forma: *dos fuentes canónicas conectadas por linkeo de frontmatter o sección, con el agente permitido (a veces obligado) a surfacear el delta*. El próximo eje de aplicación — sea cual sea — se reconocerá en esta tabla. + +--- + +## Anti-patrones: cómo se rompe el meta + +El meta-patrón es frágil. Cada uno de los siguientes, si se introduce, regresa la capacidad del framework para producir observaciones emergentes. + +- **Linkeo de frontmatter como opcional**. Si un nuevo tipo de documento ships con `related:` / `originating_*` como advisory en lugar de obligatorio, el grafo de cross-referencing desarrolla blind spots y el agente pierde la capacidad de triangular a través de ese tipo. +- **Secciones canónicas colapsadas en prosa**. Si `§Risk: R` se reemplaza por *"discusión de riesgos"*, la queryability se evapora. El agente ya no puede contar entradas `R` para detectar el umbral de saturación que dispara `refresh-suggest`. La prosa libre no es queryable; las secciones estructuradas sí. +- **Gatekeeping en docs creados por agente**. Requerir pre-aprobación para fillar AILOG / AIDEC / TDE mata la Propiedad 2. El agente regresa a surfacear sólo lo pedido, porque el costo de surfacear sube por encima del beneficio local. +- **Telemetría sin signals emergentes**. Si los schemas de `.telemetry.yaml` evolucionan sin preservar signals como `r_n_plus_one_emergent_count`, el operador pierde visibilidad de qué tan seguido el agente está surfaceando riesgos emergentes. El feedback loop se rompe; el meta se vuelve invisible a la evolución del framework. +- **Comandos CLI que bypasean la superficie**. Una CLI que emite decisiones directamente (sin AILOG escrito, sin sección `R` poblada) bypasea la superficie estructural. La triangulación río abajo del agente se degrada porque el par de fuentes ya no está conectado vía documentos. + +--- + +## Ejes de aplicación abiertos — dónde el meta podría replicarse + +La auditoría subyacente a este documento identificó cuatro loci donde la infraestructura estructural existe *parcialmente* pero el permiso cultural o el patrón de aplicación no han sido nombrados. Son candidatos a futura aplicación del meta, no commitments de shipping. + +- **MCARD ↔ código del modelo desplegado** — `TEMPLATE-MCARD.md` existe; no hay campo `model-version-at-close` en telemetría de Charter, no hay campo de linkeo AILOG `deployed_mcard:`, no hay patrón de detección de drift. Un despliegue de modelo que diverge de la MCARD on file es actualmente invisible. +- **SBOM ↔ lockfiles** — `AI-RISK-CATALOG.md` §RISK-004 menciona mantenimiento de SBOM para componentes AI; no hay campo canónico de AILOG enlazando a SBOM, no hay script de drift (análogo a `check-followups-drift.sh`) que compare SBOM declarada contra `package.lock` / `requirements.txt` real, no hay signal de telemetría para eventos de cambio de dependencias. +- **ADR vigente ↔ implementación que contradice** — el schema de `.telemetry.yaml` captura `decisions_contradicting_prior_adrs` pero ningún protocolo le dice al agente *cuándo* surfacear una contradicción que observa durante implementación. El signal existe; la convención de surfacing no. +- **Constitution Check ↔ bump de versión del framework** — `SPECKIT-CHARTER-BRIDGE.md §Constitution Check re-evaluation cadence` codifica la cadencia verbalmente; no se dispara alerta automática en `straymark update-framework`. Un bump del framework entre Charters puede cambiar los gates de Constitution silenciosamente. + +Estos cuatro están trackeados en un único Issue upstream de RFC (filed después de que este documento aterrice). Cada uno requiere validación N=1 empírica de un adopter antes de cristalizar como patrón nombrado — aplica el Principio #12. + +--- + +## Authority / flujo de aceptación para nombrar nuevas meta-aplicaciones + +El mismo flujo de aceptación upstream que `CHARTER-CHAIN-EVOLUTION.md` documenta aplica recursivamente a este meta. Un nuevo eje de aplicación (uno de los cuatro arriba, o un quinto que emerja) aterriza así: + +1. **RFC adopter-local** en `.straymark/06-evolution/-rfc.md` describiendo la conexión estructural que ya existe (o se está añadiendo) y la regla de permiso cultural que el agente debe seguir. +2. **Issue upstream** espejando el RFC, citando los AILOGs/Charters/telemetría donde ocurrió la observación empírica. +3. **Aceptación upstream** como: (a) actualización del template / schema / doc de governance relevante para añadir la pieza estructural faltante (campo de frontmatter, sección canónica, signal de telemetría); (b) adición del eje a la tabla "Pirámide de instancias" en este documento; (c) scaffolding CLI opcional para detección mecánica. +4. **Validación de segundo dominio** antes de que las adiciones de schema del eje gradúen de opcionales a recomendadas. + +Este propio documento instancia el paso 3.b para el meta — el output de aceptación upstream de reconocer que las aplicaciones existentes comparten una propiedad subyacente única. + +--- + +## Preguntas abiertas + +- **Operacionalización de "divergencia material"**. El texto del Principio #8 ([`PRINCIPLES.md`](PRINCIPLES.md)) deja "material" al juicio del agente. Los umbrales por-aplicación (Pattern 1 usa media móvil `r_n_plus_one_emergent_count > 6`) se calibran empíricamente. Si un umbral cross-axis es alcanzable, o si cada eje debe calibrar el suyo, queda abierto. +- **Consolidación de telemetría**. Cada aplicación emite actualmente su propio slot de telemetría (`pre_declare_refresh:`, `post_close_amendment:`, `r_n_plus_one_emergent_count`). Un contador consolidado *"observaciones emergentes surfaceadas en este Charter"* podría hacer el meta visible a nivel de métricas. Diferido — agregación prematura arriesga perder granularidad de signal por-eje. +- **Onboarding de adopters**. Adopters nuevos leyendo `STRAYMARK.md` por primera vez deberían encontrar el meta lo suficientemente temprano como para reconocer el patrón cuando lo experimenten. Si eso vive en `QUICK-REFERENCE.md`, en `STRAYMARK.md` mismo, o en una nueva sección de onboarding, queda abierto. + +--- + +## Relacionados + +- [`PRINCIPLES.md`](PRINCIPLES.md) §8 — *Surfacing de disonancia entre fuentes* (la regla cultural, condensada). +- [`AGENT-RULES.md`](AGENT-RULES.md) §6 — *Be Proactive* (el mandato operativo); §3 — *TDE vs `R`* (una superficie de aplicación); §12 — *Audit Checkpoint* (surfacing institucionalizado). +- [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) — Pattern 1, Pattern 2 (las dos aplicaciones de más alto nivel). +- [`SPECKIT-CHARTER-BRIDGE.md`](SPECKIT-CHARTER-BRIDGE.md) — Charter como la capa bridge donde el linkeo de la Propiedad 1 es más denso. +- [`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md) — detección de drift en la superficie per-AILOG ↔ registro. +- [`DOCUMENTATION-POLICY.md`](DOCUMENTATION-POLICY.md) — canon de frontmatter y campo `related:`. +- [`../../STRAYMARK.md`](../../STRAYMARK.md) §15 — Charter como la unidad bounded donde las aplicaciones convergen. + +--- + +*StrayMark fw-4.17.0 | [GitHub](https://github.com/StrangeDaysTech/straymark) | Issue [#150](https://github.com/StrangeDaysTech/straymark/issues/150) · [#156](https://github.com/StrangeDaysTech/straymark/issues/156)* diff --git a/.straymark/00-governance/i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md b/.straymark/00-governance/i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md new file mode 100644 index 0000000..492eaab --- /dev/null +++ b/.straymark/00-governance/i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md @@ -0,0 +1,244 @@ +# Patrón de Backlog de Follow-ups - StrayMark + +> Convención reproducible para gestionar entradas acumuladas de `§Follow-ups` y `R (new, not in Charter)` a lo largo de muchos AILOGs y Charters. + +**Idiomas**: [English](../../FOLLOW-UPS-BACKLOG-PATTERN.md) | Español | [简体中文](../zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md) + +--- + +## Estado + +**v0 — validado en N=1 dominio** (`StrangeDaysTech/sentinel` CHARTER-12, 2026-05-06). + +Esto es una **convención**, no una funcionalidad del CLI. Los adopters la reproducen localmente con markdown + un script bash portable. El patrón puede evolucionar a un subcomando `straymark followups` una vez que un segundo adopter lo valide (ver [Preguntas abiertas](#preguntas-abiertas)). + +--- + +## Cuándo aplica este patrón + +La convención per-AILOG `§Follow-ups` de StrayMark funciona en tiempo de escritura — cuando se crea un AILOG, el implementador documenta lo que se difiere a Charters subsiguientes o triggers operativos. Eso funciona bien hasta que la lista acumulada crece más allá de lo que un operador puede escanear de memoria. + +Adopta este patrón cuando se cumpla **cualquiera** de estas condiciones: + +- El proyecto ha acumulado **~20 o más AILOGs** con secciones `§Follow-ups` no triviales. +- Los operadores piden repetidamente a los agentes "lista qué está pendiente en el proyecto" y la respuesta requiere un escaneo multi-archivo. +- Un follow-up de tipo "haz esto cuando llegue X" estuvo a punto de perderse porque el AILOG originador nunca fue releído después de que llegó X. +- Una retrospectiva de Charter aflora follow-ups que deberían haber sido clasificados como `closed` semanas antes pero nunca fueron indexados. + +Por debajo de ese volumen, la convención per-AILOG por sí sola es suficiente — adoptar este patrón temprano agrega overhead de mantenimiento sin retorno. + +--- + +## Forma + +### Archivo de registro + +Único archivo markdown en la ruta canónica: + +``` +.straymark/follow-ups-backlog.md +``` + +### Frontmatter (YAML) + +```yaml +--- +last_scan: 2026-05-06 +last_scan_range: AILOG-NNNN-NN-NN-NNN..AILOG-NNNN-NN-NN-NNN # opcional — primer..último AILOG cubierto +schema_version: v0 +total_open: 0 # cuenta de entradas actualmente `open` +total_promoted: 0 # cuenta de entradas actualmente `promoted` (agregado en schema v0.1 — ver "Promoción a TDE") +total_closed_in_session: 0 # cuenta de entradas `closed` desde la última sesión (opcional, operator-maintained) +total_phase_blocked: 0 # cuenta de entradas `phase-blocked` (opcional) +buckets: + - ready + - time-triggered + - charter-triggered + - phase-blocked + - operational +fully_extracted_ailogs: + - AILOG-2026-04-11-001 + - AILOG-2026-04-12-001 + # ... una entrada por cada AILOG cuyos follow-ups han sido procesados +--- +``` + +Los contadores `total_*` son **metadatos operator-maintained**. El script de drift no los actualiza automáticamente — viven en el header para que un vistazo a inicio de sesión muestre el pulso del registro sin scrollear por buckets. `total_promoted` se canonicalizó en schema v0.1 (señal empírica del adopter Sentinel, fw-4.13.1) para reflejar el patrón existente de `total_open` / `total_closed_in_session` / `total_phase_blocked`. + +La lista `fully_extracted_ailogs` es el **metadato cargante** para la detección de drift. Todo AILOG cuyas entradas de `§Follow-ups` y `R` han sido transferidas al registro (o explícitamente clasificadas como superseded) pertenece a esta lista. La detección de drift compara esta lista contra los AILOGs que tienen contenido de follow-ups en el repo. + +### Buckets + +Cinco buckets organizan las entradas por tipo de trigger: + +- `ready` — accionable ahora, sin dependencia de trigger externo. +- `time-triggered` — trigger basado en calendario (ciclo de auditoría, revisión periódica). +- `charter-triggered` — bloqueado por un Charter futuro que toque el área relevante. +- `phase-blocked` — bloqueado por un componente o fase futura que aún no existe. +- `operational` — decisión manual del operador o acción de sistema externo. + +### Esquema de entrada + +Cada entrada dentro de un bucket sigue esta forma: + +```markdown +### FU-NNN — +- **Origin**: AILOG-NNNN-NN-NN-NNN +- **Status**: open | in-progress | closed | superseded | promoted +- **Trigger**: ready | | when | +- **Destination**: +- **Cost**: +- **Notes**: +- **Promoted to**: +``` + +`FU-NNN` es monotónicamente creciente a lo largo de la vida del registro; no se renumera cuando las entradas se cierran. + +### Vocabulario de status + +- `open` — pendiente, sin acción aún. +- `in-progress` — un Charter ha sido declarado o está en ejecución para atender esta entrada. +- `closed` — entrada resuelta (Charter mergeado, tarea operativa hecha, tiempo transcurrido y revisado). +- `superseded` — atendida por otro trabajo que no referenció esta entrada directamente. +- `promoted` — la entrada fue elevada a un documento TDE porque cumple los criterios de deuda transversal (ver "Promoción a TDE" abajo). El campo `Promoted to:` carga el id del TDE. + +Las entradas closed, superseded y promoted permanecen en el archivo (historia auditable). Los operadores pueden moverlas a una sección `## Bucket: closed` al final para limpieza visual, pero nunca se eliminan. + +--- + +## Promoción a TDE + +Algunas entradas FU no son solo tareas diferidas — describen **deuda técnica transversal** que merece su propio documento de gobernanza (TDE). Los criterios para promoción reflejan la desambiguación TDE-vs-`R` en `AGENT-RULES.md §3`: + +- La entrada es *herencia de un Charter previo* (ya vivió ≥1 cierre de Charter sin remediación). +- La entrada *aplica a múltiples módulos o múltiples Charters* — el registro central la ha fragmentado en bullets que comparten una causa raíz. +- La entrada *requiere un Charter dedicado fuera del envelope de scope actual* para remediarse. +- La entrada *requiere priorización o asignación humana* que la revisión periódica del operador no puede decidir desde el bullet solo (matriz impact × effort, ownership). + +Cuando cualquiera de estos se cumple, promueve la entrada FU a un documento TDE bajo `.straymark/06-evolution/technical-debt/`: + +1. Crea el TDE vía `/straymark-new tde` (o `straymark new --type tde`). Llena `impact`, `effort`, `type`, y las secciones del body desde el contexto de la entrada FU. +2. Agrega `promoted_from_followup: FU-NNN` al frontmatter del TDE para trazabilidad. +3. En la entrada FU, establece `Status: promoted`, `Destination: TDE-YYYY-MM-DD-NNN`, y agrega `Promoted to: TDE-YYYY-MM-DD-NNN`. Mueve la entrada a la sección `## Bucket: closed` si mantienes una; si no, déjala en lugar con el nuevo status. + +La entrada FU **no se elimina** tras la promoción — su presencia en el registro es el rastro auditable que muestra de dónde vino el TDE. + +### Dos formas de promoción — promoción-de-existente vs retroactiva-en-la-creación + +El workflow anterior cubre el **caso estándar**: una entrada FU `open` ya existe en el registro y se eleva a un TDE durante revisión periódica. Existe un segundo caso igualmente válido que emergió empíricamente del retrospectivo de Sentinel CHARTER-13: + +- **Promoción de entrada existente** — un FU fue registrado (típicamente vía `--apply`) como `open` semanas o Charters atrás, vivió ≥1 cierre de Charter sin resolución, y cumple los cuatro criterios. Flujo estándar. +- **Promoción retroactiva en la creación** — la deuda se reconoce como TDE-worthy *durante* un retrospectivo (ceremonia de cierre de Charter, ciclo de auditoría, redacción de RFC) y nunca existió como FU `open`. Se crea primero el TDE; se agrega una entrada FU al registro *con `Status: promoted`* desde el nacimiento, proporcionando el rastro auditable desde el TDE hacia el contexto originador (un `R` en un AILOG, un finding del calibrador, una clasificación diferida). + +Ambas formas producen el mismo estado final en el registro: una entrada con `Status: promoted` y un puntero `Promoted to: TDE-YYYY-MM-DD-NNN`. La diferencia es si la entrada pre-existía como `open` o nació `promoted`. El script de drift las trata idénticamente (no diferencia por status de nacimiento), y las analíticas del adopter que cuentan `total_promoted` obtienen el mismo número en ambos casos. + +Ante la duda, prefiere crear la entrada FU — aunque sea retroactivamente — porque cross-referencia el TDE de vuelta al AILOG / número-R / contexto fuente que disparó el reconocimiento. Un TDE con `promoted_from_followup: FU-NNN` apuntando a una entrada que existe en el backlog es más navegable que uno apuntando a un FU ficticio. + +### Cuándo promover + +- **Revisión periódica** — cuando el operador hace el pase manual de reclasificación, promueve cualquier entrada que haya vivido ≥2 cierres de Charter sin resolución y cumpla los criterios anteriores. +- **Cierre de Charter** — al revisar entradas que el Charter recién cerrado resolvió, si encuentras entradas que *no* fueron resueltas y cumplen los criterios anteriores, promuévelas en vez de dejarlas como `open`. +- **Pre-declaración de Charter** — si estás a punto de declarar un Charter y notas que el registro contiene entradas que este Charter *parcialmente* atendería, la porción no atendida puede pertenecer como TDE en vez de como otro FU diferido. + +El script de drift (`scripts/check-followups-drift.sh`) **no se extiende** para candidatos a promoción en v0 — la promoción es operator-driven. Una mejora futura v1 podría flagear entradas que cumplan la heurística "vivió ≥2 Charters", pero eso cristaliza tras un segundo adopter que valide el patrón (misma puerta que el resto de v0 → v1). + +--- + +## Detección de drift + +Un pequeño script bash es la capa de verificación que mantiene el registro sincronizado con nuevos AILOGs. El script vive en el repo del adopter (ruta sugerida: `scripts/check-followups-drift.sh`) y tiene tres modos. + +### Modos + +- **Default** — escanea AILOGs modificados en `git diff origin/main..HEAD` (con fallback a `HEAD~1..HEAD`). Avisa sobre cualquier AILOG con contenido `§Follow-ups` / `R (new)` que no esté en `fully_extracted_ailogs`. Sale con 1 si hay drift. +- **`--apply`** — mismo escaneo, pero auto-agrega nuevas entradas bajo `## Bucket: ready` con ids `FU-NNN` auto-generados y agrega el id del AILOG a `fully_extracted_ailogs`. El operador reclasifica al bucket correcto después. +- **`--scan-all`** — escanea cada AILOG en el proyecto (barrido completo periódico). + +### Granularidad per-AILOG vs per-bullet + +El tracking es **per-AILOG**, no per-bullet. Un AILOG está totalmente extraído (su id está en `fully_extracted_ailogs` — confiar en el registro) o no lo está (extraer todo). El matching per-bullet requeriría fingerprinting (hashing de texto o comparación fuzzy), que produce falsos positivos cada vez que una entrada del registro parafrasea el bullet del AILOG — y las entradas curadas siempre parafrasean. + +El costo de la granularidad per-AILOG: cuando se agrega un follow-up a un AILOG ya extraído tras el cierre del Charter, la detección de drift no lo detecta. La remediación es manual del operador — quitar el AILOG de `fully_extracted_ailogs` y re-correr con `--apply`. Este trade-off es intencional para v0 porque la mayoría de AILOGs son write-once tras el cierre del Charter. + +### Plantilla de script + +Una implementación de referencia (~290 líneas de bash POSIX) está en `StrangeDaysTech/sentinel` en `scripts/check-followups-drift.sh`. Cópiala a tu repo y ajusta las constantes al inicio: + +```bash +BACKLOG_FILE=".straymark/follow-ups-backlog.md" +AILOG_DIR=".straymark/07-ai-audit/agent-logs" +``` + +El script usa solo `awk` y `grep` — sin jq, sin yq, sin dependencias pesadas. Portable entre Linux y macOS. + +--- + +## Integración con agentes + +El agente (Claude / Gemini / etc.) se vuelve el mantenedor primario del registro. Agrega a tu `CLAUDE.md` / `AGENT.md`: + +```markdown +## Backlog de follow-ups + +- **Inicio de sesión**: revisar `.straymark/follow-ups-backlog.md` para saber qué está pendiente en el proyecto. +- **Checklist pre-commit**: ¿creaste o modificaste algún AILOG con entradas `## Follow-ups` o `R (new, not in Charter)`? → ejecuta `scripts/check-followups-drift.sh --apply` para extender el backlog en el mismo commit. +- **Post-cierre de Charter**: revisar entradas que el Charter resolvió; marcarlas `closed` (con el id del Charter de cierre en `Notes`) o `superseded`. Para entradas no resueltas que cumplen los criterios de TDE (herencia de Charter previo, transversal, requiere Charter dedicado, necesita priorización humana), promuévelas a un documento TDE (ver "Promoción a TDE" en este patrón + `AGENT-RULES.md §3`). +``` + +Esto hace al agente el mantenedor, al script la capa de verificación, y al operador el revisor periódico (re-bucketing, marcar closed, podar superseded, promover a TDE cuando los criterios aplican). + +--- + +## Walkthrough de adopción + +Para un adopter empezando desde cero: + +1. Crear `.straymark/follow-ups-backlog.md` con el frontmatter de arriba (lista `fully_extracted_ailogs:` vacía inicialmente) y los cinco headers `## Bucket: `. +2. Copiar el script de referencia desde `StrangeDaysTech/sentinel` a `scripts/check-followups-drift.sh`. Ajustar `AILOG_DIR` si tus AILOGs viven en otro lado. +3. Ejecutar `scripts/check-followups-drift.sh --scan-all --apply` para sembrar el registro desde AILOGs existentes. +4. Reclasificar manualmente las entradas auto-generadas en `## Bucket: ready` a los buckets correctos. Esto es triage one-time, típicamente 30-60 min para un backlog de ~50 entradas. +5. Agregar el bloque de integración con agentes a `CLAUDE.md` / `AGENT.md`. +6. Opcionalmente conectar `scripts/check-followups-drift.sh` a un pre-commit hook para enforcement duro. + +Para un adopter migrando desde tracking ad-hoc: el mismo flujo, pero el paso 4 puede requerir decidir qué entradas ya están `closed` o `superseded` — esa clasificación es lo que hace al registro útil. + +--- + +## Implementación de referencia + +`StrangeDaysTech/sentinel` CHARTER-12, mergeado 2026-05-06: + +- PR de implementación: [sentinel#53](https://github.com/StrangeDaysTech/sentinel/pull/53) (registro + script + adiciones a CLAUDE.md). +- PR de cierre: [sentinel#54](https://github.com/StrangeDaysTech/sentinel/pull/54) (verificación post-merge + cierre del Charter). + +Contexto empírico: 47 entradas sembradas desde la retrospectiva CHARTER-08 → CHARTER-11 (~30 min de triage multi-agente). La cadena demostró el gap que motivó el patrón — sin el registro, el operador no podía ver "qué está pendiente en el proyecto" sin reclasificar los follow-ups de cada Charter en aislamiento. Con el registro, la revisión de inicio de sesión es una sola lectura de archivo. + +--- + +## Preguntas abiertas + +Estas no se resuelven en v0. Revisiones futuras de este patrón, o un helper CLI, pueden atenderlas: + +- **Heurística de clasificación de bucket**. Hoy `--apply` vuelca cada entrada nueva a `## Bucket: ready`; el operador reclasifica manualmente. Una heurística usando `tags` del AILOG y `effort_estimate` del Charter podría sugerir un bucket automáticamente. +- **Validación de schema**. El registro sigue un esquema tácito; aún no existe `.straymark/schemas/follow-ups-backlog.schema.v0.json`. La validación hoy es revisión humana. +- **Integración con el ciclo de auditoría**. Cuando `straymark charter audit --merge-reports` produce findings de deuda real que no son remediados atómicamente pre-cierre, esos findings viven solo en `.straymark/audits//review.md`. No fluyen automáticamente al registro central. Aflorarlos automáticamente cerraría un gap conocido. +- **Semántica `closed` vs `superseded`**. Hoy la diferencia es si el trabajo de resolución referenció explícitamente la entrada. Una convención más estricta puede emerger. +- **Cristalización como CLI `straymark followups`**. Una vez que un segundo adopter valide el patrón, el framework puede shippear un subcomando que espeje al trío existente `straymark charter`: `list` / `close` / `drift`. Los adopters en v0 (este patrón) migran borrando su script local y cambiando la instrucción del agente. + +--- + +## Créditos + +Contribuido vía [issue #111](https://github.com/StrangeDaysTech/straymark/issues/111) por el adopter Sentinel. Fundamento empírico: cadena CHARTER-08 → CHARTER-11 en `StrangeDaysTech/sentinel`. Autor: Claude Opus 4.7 a nombre del operador José Villaseñor Montfort. + +--- + +## Relacionado + +- [EMERGENT-OBSERVATION-DESIGN.md](EMERGENT-OBSERVATION-DESIGN.md) — el meta-patrón que esta convención de detección de drift instancia en la superficie per-AILOG ↔ registro. +- [CHARTER-CHAIN-EVOLUTION.md](CHARTER-CHAIN-EVOLUTION.md) — patrón hermano que opera a nivel de cadena (Pattern 1) y a nivel de ciclo (Pattern 2). +- [AGENT-RULES.md §3](AGENT-RULES.md) — criterios de escalación TDE-vs-`R` que pueden promover follow-ups a entradas de deuda dedicadas. + +--- + +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/00-governance/i18n/es/GB-45438-LABELING-GUIDE.md b/.straymark/00-governance/i18n/es/GB-45438-LABELING-GUIDE.md new file mode 100644 index 0000000..139258d --- /dev/null +++ b/.straymark/00-governance/i18n/es/GB-45438-LABELING-GUIDE.md @@ -0,0 +1,118 @@ +# Guía de Etiquetado de Contenido GB 45438 — StrayMark + +> Guía práctica para completar un documento AILABEL bajo **GB 45438-2025** *Cybersecurity Technology — Labeling Method for Content Generated by Artificial Intelligence* y las *Measures for the Identification of AI-Generated (Synthetic) Content* del CAC. + +**Languages**: [English](../../GB-45438-LABELING-GUIDE.md) | Español | [简体中文](../zh-CN/GB-45438-LABELING-GUIDE.md) + +--- + +## Estado + +GB 45438-2025 es un estándar técnico nacional **obligatorio**, vigente desde **2025-09-01**. Las medidas del CAC son la regulación operativa que da fuerza al estándar: cualquier servicio en alcance debe implementar etiquetado **explícito** (visible) **e implícito** (legible por máquina). + +Un servicio está en alcance cuando genera, sintetiza, o modifica sustancialmente cualquiera: + +- Texto (chat, resumen, traducción) +- Imágenes (text-to-image, edición, face-swap, manipulación de poses) +- Audio (clonación de voz, TTS, generación de música) +- Vídeo (text-to-video, image-to-video, deep synthesis) +- Escenas virtuales (entornos inmersivos / hiperrealistas) + +Si aplica, setee `gb45438_applicable: true` en el MCARD y cree un AILABEL. La regla **CROSS-010** aplica el enlace. + +--- + +## Etiquetado de Doble Pista + +### Etiquetas Explícitas (Visibles) + +Deben ser perceptibles por un usuario común. La forma depende del medio: + +| Medio | Formas aceptables | +|-------|-------------------| +| Texto | Disclaimer, banner, etiqueta inline al inicio o final del mensaje | +| Imagen | Watermark visible (corner badge, opacity overlay), caption | +| Audio | Audio cue al inicio del clip, disclosure hablado periódico para clips largos | +| Vídeo | Watermark persistente + disclosure en el primer frame | +| Escena virtual | HUD banner persistente o aviso pre-entrada | + +La etiqueta explícita debe permanecer **prominente** y **legible** bajo condiciones razonables de visualización. + +### Etiquetas Implícitas (Legibles por Máquina) + +Embeber metadatos en cabeceras de archivo. El estándar exige **al mínimo**: + +- `content_type` — uno de `text` / `image` / `audio` / `video` / `virtual_scene` +- `service_provider_code` — emitido por CAC tras filing (link al CACFILE) +- `content_id` — identificador único por artefacto (UUIDv7 / ULID recomendado) + +La plantilla AILABEL captura estos campos en la sección 3.2. + +GB 45438 **fomenta** (no obliga) marcas de agua digitales para persistencia adicional — ver § 3.3 del AILABEL. + +--- + +## Eligiendo Formato de Metadatos + +| Formato | Pros | Contras | +|---------|------|---------| +| **C2PA** (Content Credentials) | Estándar de industria, firmado, ecosistema amplio | Más pesado; requiere PKI | +| **XMP** | Maduro en image/video tooling | Frecuentemente stripeado por plataformas sociales | +| **EXIF** | Universal en image tooling | Limitado a imágenes; trivialmente stripeable | +| **Custom** | Campos a medida | Requiere cooperación del distribuidor | +| **None** | — | No conforme con GB 45438 | + +Para servicios solo-texto, puede codificar el metadata implícito como caracteres Unicode de uso privado o como envelope JSON. Documente la elección en la sección 3.1. + +--- + +## Requisitos de Persistencia + +GB 45438 espera que las etiquetas implícitas persistan cuando los archivos se descargan, exportan o copian. Provea evidencia en la sección 4 del AILABEL: + +| Operación | Test | +|-----------|------| +| Descarga directa | Re-leer el metadata desde el archivo descargado | +| Re-exportación con otra herramienta | Abrir en editor de terceros, guardar, re-leer | +| Captura de pantalla | Watermark sobrevive aunque metadata se pierda | +| Re-codificación | Watermark robusto sobrevive re-codificación JPEG/MPEG | + +Si la etiqueta explícita no puede sobrevivir (ej. screenshot de texto plano), la etiqueta **implícita** o un **watermark visible robusto** debe. + +--- + +## Obligaciones del Distribuidor + +Plataformas que distribuyen contenido generado por IA deben: +- Verificar metadata cuando esté presente. +- Mostrar prominentemente un prompt al espectador cuando se identifica contenido sintético. +- No remover ni alterar etiquetas existentes. + +Si su servicio distribuye contenido de proveedores upstream, documente en la sección 5 del AILABEL cómo implementa estas obligaciones. Setee `gb45438_distributor_obligations_documented: true` cuando esté completo. + +--- + +## Vinculación con Otros Frameworks + +GB 45438 no opera aislado: + +| Framework | Interacción | +|-----------|-------------| +| **CAC Algorithm Filing** | El `service_provider_code` en el metadata implícito es **emitido por CAC** tras un filing exitoso. El AILABEL debe referenciar el CACFILE. | +| **EU AI Act Art. 50** | UE tiene obligación de transparencia paralela. Un único diseño puede satisfacer ambos, pero idiomas y superficies de verificación pueden diferir. | +| **TC260 v2.0** | Fallo de etiquetado debe aparecer como `application_risk` en el TC260RA cuando `gb45438_applicable: true`. | +| **C2PA / W3C Provenance** | Estándares de industria convergiendo con GB 45438. Elegir C2PA alinea requisitos globales y chinos. | + +--- + +## Verificaciones de Compliance + +`straymark compliance --standard china-gb45438` evalúa: + +| Verificación | Valida | +|--------------|--------| +| GB45438-001 | Existe un AILABEL para cada MCARD con `gb45438_applicable: true` | +| GB45438-002 | Están poblados ambos `gb45438_explicit_label_strategy` **y** `gb45438_implicit_metadata_format` | +| GB45438-003 | Los tres campos de metadata mandatorios están documentados en el AILABEL | + + diff --git a/.devtrail/00-governance/i18n/es/GIT-BRANCHING-STRATEGY.md b/.straymark/00-governance/i18n/es/GIT-BRANCHING-STRATEGY.md similarity index 97% rename from .devtrail/00-governance/i18n/es/GIT-BRANCHING-STRATEGY.md rename to .straymark/00-governance/i18n/es/GIT-BRANCHING-STRATEGY.md index be2839f..6d69a39 100644 --- a/.devtrail/00-governance/i18n/es/GIT-BRANCHING-STRATEGY.md +++ b/.straymark/00-governance/i18n/es/GIT-BRANCHING-STRATEGY.md @@ -90,5 +90,5 @@ git push -u origin fix/commits-accidentales --- -*DevTrail v1.0.0 | Última actualización: 2025-01-30* +*StrayMark v1.0.0 | Última actualización: 2025-01-30* *[Strange Days Tech](https://strangedays.tech) — Porque cada cambio cuenta una historia.* diff --git a/.straymark/00-governance/i18n/es/ISO-25010-2023-REFERENCE.md b/.straymark/00-governance/i18n/es/ISO-25010-2023-REFERENCE.md new file mode 100644 index 0000000..44bfaa8 --- /dev/null +++ b/.straymark/00-governance/i18n/es/ISO-25010-2023-REFERENCE.md @@ -0,0 +1,150 @@ +# ISO/IEC 25010:2023 — Referencia de calidad de software + +> **Estándar**: ISO/IEC 25010:2023 — Systems and software Quality Requirements and Evaluation (SQuaRE) — Modelo de calidad del producto +> **Reemplaza**: ISO/IEC 25010:2011 +> **Propósito**: Documento de referencia para las plantillas StrayMark (ADR, REQ) que evalúan características de calidad de software. + +--- + +## Características de calidad (2023 vs 2011) + +La revisión 2023 actualiza el modelo de 8 a **9 características**, con renombres y reestructuraciones importantes. + +| # | Característica (2023) | Nombre anterior (2011) | Cambio | +|---|----------------------|------------------------|--------| +| 1 | **Adecuación funcional** | Adecuación funcional | Sin cambios | +| 2 | **Eficiencia de desempeño** | Eficiencia de desempeño | Sin cambios | +| 3 | **Compatibilidad** | Compatibilidad | Sin cambios | +| 4 | **Capacidad de interacción** | Usabilidad | Renombrada | +| 5 | **Confiabilidad** | Confiabilidad | Reestructurada | +| 6 | **Seguridad** | Seguridad | Nueva sub: Resistencia | +| 7 | **Mantenibilidad** | Mantenibilidad | Sin cambios | +| 8 | **Flexibilidad** | Portabilidad | Renombrada | +| 9 | **Seguridad funcional (Safety)** | *(nueva)* | Característica nueva | + +--- + +## Características y sub-características detalladas + +### 1. Adecuación funcional + +Grado en el que un producto provee funciones que cumplen las necesidades declaradas e implícitas. + +| Sub-característica | Descripción | +|--------------------|-------------| +| Completitud funcional | Grado en el que el conjunto de funciones cubre todas las tareas y objetivos de usuario especificados | +| Corrección funcional | Grado en el que un producto provee resultados correctos con la precisión requerida | +| Pertinencia funcional | Grado en el que las funciones facilitan el cumplimiento de tareas y objetivos especificados | + +### 2. Eficiencia de desempeño + +Desempeño relativo a la cantidad de recursos usados bajo condiciones declaradas. + +| Sub-característica | Descripción | +|--------------------|-------------| +| Comportamiento temporal | Grado en el que los tiempos de respuesta, procesamiento y throughput cumplen los requisitos | +| Utilización de recursos | Grado en el que las cantidades y tipos de recursos usados cumplen los requisitos | +| Capacidad | Grado en el que los límites máximos de un parámetro del producto cumplen los requisitos | + +### 3. Compatibilidad + +Grado en el que un producto puede intercambiar información y realizar sus funciones requeridas compartiendo el mismo entorno. + +| Sub-característica | Descripción | +|--------------------|-------------| +| Coexistencia | Grado en el que un producto realiza sus funciones eficientemente compartiendo un entorno y recursos comunes con otros productos | +| Interoperabilidad | Grado en el que dos o más sistemas pueden intercambiar información y usarla | + +### 4. Capacidad de interacción *(renombrada desde Usabilidad)* + +Grado en el que un producto puede ser usado por usuarios especificados para lograr objetivos especificados con eficacia, eficiencia y satisfacción. + +| Sub-característica | Descripción | Cambio respecto a 2011 | +|--------------------|-------------|------------------------| +| Reconocibilidad de pertinencia | Grado en el que los usuarios pueden reconocer si un producto es apropiado para sus necesidades | Sin cambios | +| Aprendibilidad | Grado en el que un producto puede ser usado para alcanzar objetivos de aprendizaje especificados con eficacia, eficiencia, ausencia de riesgo y satisfacción | Sin cambios | +| Operabilidad | Grado en el que un producto tiene atributos que lo hacen fácil de operar y controlar | Sin cambios | +| Protección frente a errores de usuario | Grado en el que un producto protege a los usuarios contra cometer errores | Sin cambios | +| Compromiso del usuario | Grado en el que un producto provee una experiencia de interacción atractiva y motivadora | Reemplaza a "Estética de la interfaz de usuario" | +| Inclusividad | Grado en el que un producto puede ser usado por personas con el rango más amplio de características y capacidades | Separada de Accesibilidad | +| Asistencia al usuario | Grado en el que un producto provee ayuda y guía apropiadas a los usuarios | Separada de Accesibilidad | +| Auto-descripción | Grado en el que un producto presenta información que hace sus capacidades y uso inmediatamente obvios | Nueva | + +### 5. Confiabilidad + +Grado en el que un sistema realiza las funciones especificadas bajo condiciones especificadas durante un periodo de tiempo especificado. + +| Sub-característica | Descripción | Cambio respecto a 2011 | +|--------------------|-------------|------------------------| +| Ausencia de fallos | Grado en el que un sistema opera sin fallos bajo condiciones normales | Reemplaza a "Madurez" | +| Disponibilidad | Grado en el que un sistema está operativo y accesible cuando se requiere para uso | Sin cambios | +| Tolerancia a fallos | Grado en el que un sistema opera como se pretende a pesar de fallos de hardware o software | Sin cambios | +| Recuperabilidad | Grado en el que un producto puede recuperar datos y reestablecer el estado deseado después de una interrupción o fallo | Sin cambios | + +### 6. Seguridad + +Grado en el que un producto protege información y datos. + +| Sub-característica | Descripción | Cambio respecto a 2011 | +|--------------------|-------------|------------------------| +| Confidencialidad | Grado en el que los datos son accesibles sólo para quienes están autorizados a tener acceso | Sin cambios | +| Integridad | Grado en el que un sistema previene el acceso no autorizado o la modificación de datos | Sin cambios | +| No repudio | Grado en el que se puede probar que acciones o eventos ocurrieron | Sin cambios | +| Trazabilidad (accountability) | Grado en el que las acciones de una entidad pueden trazarse unívocamente a la entidad | Sin cambios | +| Autenticidad | Grado en el que la identidad de un sujeto o recurso puede probarse como la declarada | Sin cambios | +| Resistencia | Grado en el que un producto resiste ataques de actores no autorizados o maliciosos | Nueva | + +### 7. Mantenibilidad + +Grado de eficacia y eficiencia con la que un producto puede ser modificado. + +| Sub-característica | Descripción | +|--------------------|-------------| +| Modularidad | Grado en el que un sistema está compuesto por componentes discretos de manera que un cambio en uno tiene impacto mínimo en los otros | +| Reusabilidad | Grado en el que un activo puede ser usado en más de un sistema o en la construcción de otros activos | +| Analizabilidad | Grado de eficacia y eficiencia con la que es posible evaluar el impacto de un cambio | +| Modificabilidad | Grado en el que un producto puede ser modificado eficaz y eficientemente sin introducir defectos | +| Testabilidad | Grado de eficacia y eficiencia con la que se pueden establecer criterios de prueba y realizar pruebas | + +### 8. Flexibilidad *(renombrada desde Portabilidad)* + +Grado en el que un producto puede ser adaptado a entornos de hardware, software o uso diferentes o cambiantes. + +| Sub-característica | Descripción | Cambio respecto a 2011 | +|--------------------|-------------|------------------------| +| Adaptabilidad | Grado en el que un producto puede ser adaptado a entornos diferentes o cambiantes | Sin cambios | +| Instalabilidad | Grado de eficacia y eficiencia con la que un producto puede ser instalado o desinstalado exitosamente | Sin cambios | +| Reemplazabilidad | Grado en el que un producto puede reemplazar a otro producto especificado para el mismo propósito en el mismo entorno | Sin cambios | +| Escalabilidad | Grado en el que un producto puede manejar cargas de trabajo crecientes o decrecientes | Nueva | + +### 9. Seguridad funcional (Safety) *(característica nueva)* + +Grado en el que un producto logra niveles aceptables de riesgo para personas, negocio, software, propiedad o el entorno. + +| Sub-característica | Descripción | +|--------------------|-------------| +| Restricción operacional | Grado en el que un producto restringe su operación dentro de parámetros o estados seguros | +| Identificación de riesgos | Grado en el que un producto identifica riesgos que podrían afectar la seguridad funcional | +| Fail safe | Grado en el que un producto automáticamente se ubica en un modo de operación seguro, o vuelve a una condición segura ante una falla | +| Advertencia de peligros | Grado en el que un producto provee advertencias de peligros | +| Integración segura | Grado en el que un producto puede mantener seguridad funcional durante y después de la integración con uno o más componentes | + +--- + +## Uso en StrayMark + +- **TEMPLATE-REQ.md**: la sección de Requisitos No Funcionales usa estas 9 características como categorías +- **TEMPLATE-ADR.md**: la sección de Consecuencias evalúa decisiones contra las características de calidad relevantes +- **TEMPLATE-TES.md**: la planificación de pruebas considera las características de calidad como dimensiones de cobertura + +## Cambios clave a recordar + +Al revisar o crear documentos StrayMark: + +1. Usar **"Capacidad de interacción"** en lugar de "Usabilidad" +2. Usar **"Flexibilidad"** en lugar de "Portabilidad" +3. Considerar siempre **"Seguridad funcional (Safety)"** como dimensión de calidad, especialmente para sistemas IA +4. **"Resistencia"** (bajo Seguridad) es relevante para evaluaciones de amenazas +5. **"Escalabilidad"** (bajo Flexibilidad) es ahora una sub-característica formal + + diff --git a/.devtrail/00-governance/i18n/es/MANAGEMENT-REVIEW-TEMPLATE.md b/.straymark/00-governance/i18n/es/MANAGEMENT-REVIEW-TEMPLATE.md similarity index 94% rename from .devtrail/00-governance/i18n/es/MANAGEMENT-REVIEW-TEMPLATE.md rename to .straymark/00-governance/i18n/es/MANAGEMENT-REVIEW-TEMPLATE.md index b00600b..8261b8f 100644 --- a/.devtrail/00-governance/i18n/es/MANAGEMENT-REVIEW-TEMPLATE.md +++ b/.straymark/00-governance/i18n/es/MANAGEMENT-REVIEW-TEMPLATE.md @@ -77,7 +77,7 @@ | Tiempo de Respuesta a Incidentes | < 24h | [Valor] | [Valor] | [Alza/Baja/Estable] | [En objetivo / En riesgo / Por debajo del objetivo] | | Puntuación de Cumplimiento | > 75% | [Valor] | [Valor] | [Alza/Baja/Estable] | [En objetivo / En riesgo / Por debajo del objetivo] | -> **Fuente**: Ejecute `devtrail metrics` para recopilar los valores actuales antes de la revisión. +> **Fuente**: Ejecute `straymark metrics` para recopilar los valores actuales antes de la revisión. #### 3.2 Estado de los Sistemas de IA (de AI-LIFECYCLE-TRACKER.md) @@ -105,7 +105,7 @@ |-----------|-------------|----------|-------------------|--------| | [ID] | [Descripción del hallazgo] | [Severidad] | [Acción tomada o planificada] | [Abierto / Cerrado] | -> **Fuente**: Ejecute `devtrail compliance --all` para generar el informe de cumplimiento antes de la revisión. +> **Fuente**: Ejecute `straymark compliance --all` para generar el informe de cumplimiento antes de la revisión. **Notas de discusión**: [Registrar discusión sobre hallazgos de auditoría y progreso de remediación] @@ -133,7 +133,7 @@ |-------|-------------|-----------|-------------------|--------| | NC-[NNN] | [Descripción de la no conformidad] | [Análisis de causa raíz] | [Acción correctiva tomada o planificada] | [Abierto / En progreso / Cerrado / Verificado] | -> **Fuente**: Documentos INC en DevTrail y fallos de `devtrail compliance`. +> **Fuente**: Documentos INC en StrayMark y fallos de `straymark compliance`. **Notas de discusión**: [Registrar discusión sobre problemas recurrentes y problemas sistémicos] @@ -177,7 +177,7 @@ --- -*Plantilla de Revisión por la Dirección — DevTrail Framework* +*Plantilla de Revisión por la Dirección — StrayMark Framework* *Alineado con ISO/IEC 42001:2023 Cláusula 9.3* - + diff --git a/.devtrail/00-governance/i18n/es/OBSERVABILITY-GUIDE.md b/.straymark/00-governance/i18n/es/OBSERVABILITY-GUIDE.md similarity index 95% rename from .devtrail/00-governance/i18n/es/OBSERVABILITY-GUIDE.md rename to .straymark/00-governance/i18n/es/OBSERVABILITY-GUIDE.md index 5a0f033..2939693 100644 --- a/.devtrail/00-governance/i18n/es/OBSERVABILITY-GUIDE.md +++ b/.straymark/00-governance/i18n/es/OBSERVABILITY-GUIDE.md @@ -1,7 +1,7 @@ -# Guía de Observabilidad — Integración de OpenTelemetry para Proyectos DevTrail +# Guía de Observabilidad — Integración de OpenTelemetry para Proyectos StrayMark > **Esta guía es opcional.** Adóptala cuando tu proyecto instrumente sistemas con OpenTelemetry. -> Complementa los documentos de gobernanza existentes de DevTrail y no reemplaza ninguno de ellos. +> Complementa los documentos de gobernanza existentes de StrayMark y no reemplaza ninguno de ellos. --- @@ -14,7 +14,7 @@ La guía cubre: - **Señales**: qué señales de telemetría recolectar y cómo se relacionan entre sí - **Configuración**: atributos de recurso, propagación de contexto y pipelines del Collector - **Políticas de datos**: qué se puede y no se puede capturar, retención y seguridad -- **Integración con DevTrail**: cómo el trabajo de observabilidad se mapea a tipos de documentos existentes +- **Integración con StrayMark**: cómo el trabajo de observabilidad se mapea a tipos de documentos existentes > **Cuándo activar esta guía**: Inclúyela en la gobernanza de tu proyecto cuando al menos un servicio emita trazas, métricas o logs estructurados vía OpenTelemetry. Documenta la decisión en un AIDEC o ADR. @@ -59,7 +59,7 @@ Los atributos de recurso identifican la fuente de datos de telemetría. Configú ## 4. Propagación de Contexto -La propagación de contexto asegura que una solicitud individual pueda ser rastreada a través de fronteras de servicio. Los proyectos DevTrail deben usar el estándar **W3C Trace Context**. +La propagación de contexto asegura que una solicitud individual pueda ser rastreada a través de fronteras de servicio. Los proyectos StrayMark deben usar el estándar **W3C Trace Context**. ### Headers @@ -174,11 +174,11 @@ En lugar de intentar bloquear cada campo sensible, define un allowlist explícit --- -## 8. Integración con DevTrail +## 8. Integración con StrayMark -El trabajo de observabilidad genera artefactos que deben documentarse dentro del framework DevTrail. Usa el siguiente mapeo para determinar qué tipo de documento crear o actualizar. +El trabajo de observabilidad genera artefactos que deben documentarse dentro del framework StrayMark. Usa el siguiente mapeo para determinar qué tipo de documento crear o actualizar. -| Cambio | Documento DevTrail | Notas | +| Cambio | Documento StrayMark | Notas | |--------|-------------------|-------| | Cambios de instrumentación (nuevos spans, atributos) | **AILOG** | Tag: `observabilidad` | | Decisión de selección de backend | **AIDEC** o **ADR** | Dependiendo del alcance; AIDEC para decisiones asistidas por IA, ADR para decisiones arquitectónicas | @@ -195,7 +195,7 @@ El trabajo de observabilidad genera artefactos que deben documentarse dentro del ## 9. Hoja de Ruta de Adopción -Adopta OpenTelemetry incrementalmente. Cada fase se construye sobre la anterior y produce documentos DevTrail específicos. +Adopta OpenTelemetry incrementalmente. Cada fase se construye sobre la anterior y produce documentos StrayMark específicos. ### Fase 0 — Decisión @@ -232,7 +232,7 @@ Adopta OpenTelemetry incrementalmente. Cada fase se construye sobre la anterior ## 10. Checklist -Usa esta lista de verificación para confirmar que la integración de OpenTelemetry de tu proyecto está completa y alineada con la gobernanza DevTrail. +Usa esta lista de verificación para confirmar que la integración de OpenTelemetry de tu proyecto está completa y alineada con la gobernanza StrayMark. - [ ] **AIDEC/ADR** documentando la decisión de adopción de OTel y selección de backend - [ ] **REQ** con requisitos de observabilidad y SLOs @@ -248,7 +248,7 @@ Usa esta lista de verificación para confirmar que la integración de OpenTeleme ## Alineación Regulatoria -La instrumentación con OpenTelemetry apoya el cumplimiento de varios frameworks regulatorios y de estándares relevantes para proyectos DevTrail. +La instrumentación con OpenTelemetry apoya el cumplimiento de varios frameworks regulatorios y de estándares relevantes para proyectos StrayMark. | Estándar | Referencia | Relevancia | |----------|-----------|------------| @@ -259,8 +259,8 @@ La instrumentación con OpenTelemetry apoya el cumplimiento de varios frameworks | **ISO/IEC 42001** | A.6.2.6 (Operación y Monitoreo) | Evidencia operativa continua de OTel apoya los requisitos de monitoreo del sistema de gestión de IA | | **ISO/IEC 42001** | A.5.2 (Evaluación de Riesgos) | Los datos operativos recolectados a través de OTel informan la evaluación continua de riesgos y mitigación | -> **Guía**: Al preparar auditorías o revisiones de compliance, usa exportaciones de datos OTel junto con documentos DevTrail (REQ, INC, ETH) para demostrar monitoreo continuo y gobernanza de datos. +> **Guía**: Al preparar auditorías o revisiones de compliance, usa exportaciones de datos OTel junto con documentos StrayMark (REQ, INC, ETH) para demostrar monitoreo continuo y gobernanza de datos. --- - + diff --git a/.straymark/00-governance/i18n/es/PIPL-PIPIA-GUIDE.md b/.straymark/00-governance/i18n/es/PIPL-PIPIA-GUIDE.md new file mode 100644 index 0000000..e7aed49 --- /dev/null +++ b/.straymark/00-governance/i18n/es/PIPL-PIPIA-GUIDE.md @@ -0,0 +1,142 @@ +# Guía PIPL / PIPIA — StrayMark + +> Guía práctica para completar una Evaluación de Impacto de Protección de Información Personal bajo la **Personal Information Protection Law** (PIPL) de China, Artículos 55-56. + +**Languages**: [English](../../PIPL-PIPIA-GUIDE.md) | Español | [简体中文](../zh-CN/PIPL-PIPIA-GUIDE.md) + +--- + +## Cuándo Se Requiere un PIPIA + +Por **PIPL Art. 55**, debe realizarse un PIPIA antes de: + +1. Procesar **información personal sensible** (Art. 28: biometría, creencias religiosas, identidad específica, salud, cuentas financieras, geolocalización, datos de menores de 14 años). +2. Usar información personal para **toma de decisiones automatizada**. +3. **Encargar** procesamiento a terceros / proveer datos a otros responsables / **divulgar públicamente** información personal. +4. **Transferir información personal** fuera de China continental. +5. Otras actividades con **impacto significativo** sobre los individuos. + +Si aplica cualquiera, setee `pipl_applicable: true` en la ETH / MCARD / AILOG correspondiente y cree un PIPIA. La regla **CROSS-005** aplica el enlace. + +--- + +## PIPIA vs. DPIA + +PIPIA (China) y DPIA (GDPR Art. 35) se solapan conceptualmente pero difieren en detalles: + +| Aspecto | DPIA (GDPR) | PIPIA (PIPL) | +|---------|------------|--------------| +| Base estatutaria | GDPR Art. 35 | PIPL Art. 55-56 | +| Umbral de disparo | "Riesgo alto" | Cualquiera de los 5 escenarios del Art. 55 | +| Elementos requeridos | Necesidad, riesgos a titulares, mitigaciones, consulta DPO | Legalidad/legitimidad/necesidad, impacto a derechos personales, riesgos de seguridad, proporcionalidad | +| Retención | No especificada por GDPR | **Mínimo 3 años** (Art. 56) | +| Consulta a autoridad | Obligatoria si riesgo residual alto | CAC provincial consultada para transferencia transfronteriza | + +Si su organización está sujeta a **ambos** GDPR y PIPL para el mismo procesamiento, lo más simple es: +- Mantener un **DPIA** como documento principal. +- Mantener un **PIPIA** que cross-referencie al DPIA vía `related: [DPIA-...]` y añada los elementos específicos PIPL. + +La plantilla DPIA ahora incluye una sección *Cross-reference: PIPIA* que apunta al revés cuando `pipl_applicable: true`. + +--- + +## Tres Elementos Obligatorios del Reporte PIPIA (Art. 56) + +Un PIPIA debe abordar: + +### 1. Legalidad / Legitimidad / Necesidad + +- **Legal** — Identificar la base legal bajo PIPL Art. 13. +- **Legítimo** — El propósito es claro, razonable y declarado. +- **Necesario** — Se procesan los datos mínimos para el propósito. + +### 2. Impacto a Derechos + Riesgos de Seguridad + +- Mapear cada derecho PIPL (Arts. 44-47, más Art. 24 opt-out de decisión automatizada) a una fila de probabilidad/severidad/mitigación. +- Identificar riesgos de confidencialidad, integridad y disponibilidad. Use la misma escala (low/medium/high) que el campo `risk_level` de StrayMark. + +### 3. Proporcionalidad de las Medidas Protectoras + +- Demostrar que las medidas son **legales, efectivas y proporcionales**. +- Documentar el riesgo residual tras cada medida. + +--- + +## Transferencia Transfronteriza (PIPL Art. 38-40) + +La transferencia transfronteriza requiere **uno** de estos mecanismos: + +| Mecanismo | Cuándo | +|-----------|--------| +| **Evaluación de Seguridad CAC** | Operadores de Infraestructura Crítica; procesadores que manejan información personal de ≥ 1M individuos; transferencia transfronteriza acumulada de ≥ 100.000 individuos o de información sensible de ≥ 10.000 individuos en cualquier período de 12 meses | +| **Certificación de Protección de Información Personal** | Alternativa voluntaria; otorgada por organismo acreditado | +| **Contrato Estándar** | Archivado con CAC provincial; adecuado para volúmenes menores | + +StrayMark no modela actualmente estos como campos estructurados (más allá de `pipl_cross_border_transfer: true`) — documente el mecanismo elegido en la sección *Cross-Border Transfer Analysis* de la plantilla PIPIA. + +--- + +## Retención + +Por Art. 56, el PIPIA y los "registros de procesamiento" deben **conservarse al menos tres años**. Setee `pipl_retention_until: YYYY-MM-DD` a una fecha al menos 3 años después de `created`. **TYPE-003** lo aplica. + +```yaml +created: 2026-04-25 +pipl_retention_until: 2029-04-25 # 3 años exactos — mínimo permitido +``` + +--- + +## Activadores de Información Personal Sensible + +Especial cuidado con estas categorías (Art. 28): + +- Identificación biométrica (huella, rostro, voz, marcha) +- Creencias religiosas +- Identidad específica +- Salud médica +- Cuentas financieras +- Seguimiento de ubicación +- Información personal de menores de 14 años + +El procesamiento requiere **consentimiento separado** y un PIPIA. Si su modelo usa cualquiera en entrenamiento o inferencia: +- Setee `pipl_sensitive_data: true` +- Documente la mitigación en *Protective Measures* del PIPIA +- Cross-referencie la sección `## Training Data` del MCARD relevante + +--- + +## Oficial de Protección de Información Personal (PIPL Art. 52) + +Un responsable que procese información personal de **más de 1.000.000 de individuos** debe designar un Oficial de Protección de Información Personal. Si aplica: +- Setee `dpo_consulted: true` en el PIPIA tras la consulta +- Documente la opinión del PIPO en *Consultation* + +--- + +## Ejemplo: Chatbot de Atención al Cliente + +Un chatbot SaaS desplegado en China continental que: +- Almacena historial de conversación (info personal) +- Usa un LLM para respuestas automatizadas (decisión automatizada) +- Envía algunas consultas a un endpoint de inferencia en el extranjero (cross-border) + +**Activadores**: 1, 2, 4 → PIPIA requerido. + +**Frontmatter**: +```yaml +id: PIPIA-2026-04-25-001 +pipl_applicable: true +pipl_article_55_trigger: cross_border +pipl_sensitive_data: false +pipl_cross_border_transfer: true +pipl_retention_until: 2029-04-25 +related: + - MCARD-2026-04-25-001 + - TC260RA-2026-04-25-001 + - DPIA-2026-04-25-001 +``` + +**Secciones a enfatizar**: análisis cross-border, decisión automatizada (Art. 24 opt-out), base legal (típicamente consentimiento), salvaguardas del receptor. + + diff --git a/.devtrail/00-governance/i18n/es/PRINCIPLES.md b/.straymark/00-governance/i18n/es/PRINCIPLES.md similarity index 64% rename from .devtrail/00-governance/i18n/es/PRINCIPLES.md rename to .straymark/00-governance/i18n/es/PRINCIPLES.md index d6d89b3..3c045f1 100644 --- a/.devtrail/00-governance/i18n/es/PRINCIPLES.md +++ b/.straymark/00-governance/i18n/es/PRINCIPLES.md @@ -1,8 +1,8 @@ -# Principios Guía - DevTrail +# Principios Guía - StrayMark > Estos principios guían todas las decisiones de documentación en el proyecto. -**Idiomas**: [English](../../PRINCIPLES.md) | Español +**Idiomas**: [English](../../PRINCIPLES.md) | Español | [简体中文](../zh-CN/PRINCIPLES.md) --- @@ -76,4 +76,16 @@ Ciertos tipos de cambios **siempre** requieren aprobación humana: --- -*DevTrail v1.0.0 | [Strange Days Tech](https://strangedays.tech)* +## 8. Surfacing de Disonancia entre Fuentes + +> **"Cuando dos fuentes canónicas se contradicen, surfacear antes de proceder."** + +Cuando el agente detecte divergencia material entre dos fuentes canónicas de la documentación StrayMark (spec ↔ código, `§Risk` de AILOG ↔ TDE backlog, ADR ↔ implementación, scope declarado de Charter ↔ commits, etc.), debe surfacearla antes de proceder con la tarea pedida. + +La documentación StrayMark está deliberadamente diseñada para hacer estas divergencias detectables: cross-referencing formal (campos de frontmatter, secciones canónicas, IDs estables) + permiso cultural para surfacear más allá de la tarea. El rol del agente es consumir esa infraestructura y reportar lo que ve. + +Ver [`EMERGENT-OBSERVATION-DESIGN.md`](EMERGENT-OBSERVATION-DESIGN.md) para el meta-patrón y la pirámide de aplicaciones existentes. + +--- + +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md b/.straymark/00-governance/i18n/es/QUICK-REFERENCE.md similarity index 63% rename from .devtrail/00-governance/i18n/es/QUICK-REFERENCE.md rename to .straymark/00-governance/i18n/es/QUICK-REFERENCE.md index dfe226a..418d584 100644 --- a/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md +++ b/.straymark/00-governance/i18n/es/QUICK-REFERENCE.md @@ -1,16 +1,16 @@ -# DevTrail - Referencia Rápida +# StrayMark - Referencia Rápida > Referencia de una página para agentes IA y desarrolladores. > > **Este es un documento derivado** — DOCUMENTATION-POLICY.md es la fuente autoritativa. -**Idiomas**: [English](../../QUICK-REFERENCE.md) | Español +**Idiomas**: [English](../../QUICK-REFERENCE.md) | Español | [简体中文](../zh-CN/QUICK-REFERENCE.md) --- ## Configuración de Idioma -**Archivo**: `.devtrail/config.yml` +**Archivo**: `.straymark/config.yml` ```yaml language: en # Opciones: en, es (por defecto: en) @@ -18,8 +18,8 @@ language: en # Opciones: en, es (por defecto: en) | Idioma | Ruta de Templates | |--------|-------------------| -| `en` | `.devtrail/templates/TEMPLATE-*.md` | -| `es` | `.devtrail/templates/i18n/es/TEMPLATE-*.md` | +| `en` | `.straymark/templates/TEMPLATE-*.md` | +| `es` | `.straymark/templates/i18n/es/TEMPLATE-*.md` | --- @@ -57,19 +57,31 @@ language: en # Opciones: en, es (por defecto: en) | `SBOM` | Lista de Materiales de Software | `07-ai-audit/` | Crear libremente | | `DPIA` | Evaluación de Impacto en Protección de Datos | `07-ai-audit/ethical-reviews/` | Borrador → aprobación (siempre) | +### Unidades de Trabajo Acotadas — Charter + +Los Charters **no** son tipos de documento — envuelven un bloque de implementación multi-sesión. El nombre de archivo usa prefijo secuencial (`NN-slug.md`), no prefijo de fecha. Ciclo de vida: `declared` → `in-progress` → `closed`. + +| Concepto | Carpeta | Autonomía del Agente | +|----------|---------|---------------------| +| `Charter` | `.straymark/charters/` (declarativo `NN-slug.md` + telemetría `NN-slug.telemetry.yaml`) | Andamiar vía `charter new`; el operador es dueño del trigger y de las transiciones de ciclo de vida | + +> Ver sección 15 de `STRAYMARK.md` y `.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md` para heurísticas de granularidad, ciclo de vida y el puente SpecKit ↔ Charter. + --- ## Cuándo Documentar | Situación | Acción | |-----------|--------| -| Código complejo (`devtrail analyze`; alternativa: >20 líneas) | AILOG | +| Código complejo (`straymark analyze`; alternativa: >20 líneas) | AILOG | | Decisión entre alternativas | AIDEC | | Cambios en auth/autorización/PII | AILOG + `risk_level: high` + ETH | | Cambios en API pública o esquema de BD | AILOG + considerar ADR | | Cambios en modelos ML/prompts | AILOG + revisión humana | | Cambios en dependencias críticas de seguridad | AILOG + revisión humana | | Cambios en instrumentación OTel | AILOG + tag `observabilidad` | +| Bloque de implementación multi-sesión (>1 día, >5 tareas en varias fases) | Declarar un **Charter** (`straymark charter new`) | +| Deuda técnica transversal (herencia de Charter previo, aplica a múltiples módulos, requiere Charter dedicado, necesita priorización humana) | **TDE** — distinto del `R` por Charter; ver AGENT-RULES.md §3 | **NO documentar**: credenciales, tokens, PII, secretos. @@ -114,7 +126,7 @@ Marcar `review_required: true` cuando: ## Estructura de Carpetas ``` -.devtrail/ +.straymark/ ├── 00-governance/ ← Políticas, AI-GOVERNANCE-POLICY.md ├── 01-requirements/ ← REQ ├── 02-design/decisions/ ← ADR @@ -128,7 +140,8 @@ Marcar `review_required: true` cuando: │ └── ethical-reviews/ ← ETH, DPIA ├── 08-security/ ← SEC ├── 09-ai-models/ ← MCARD -└── templates/ ← Plantillas +├── charters/ ← Charter (NN-slug.md + NN-slug.telemetry.yaml) +└── templates/ ← Plantillas (incl. subdir charter/) ``` --- @@ -184,8 +197,23 @@ Marcar `review_required: true` cuando: | Comando | Propósito | |---------|-----------| -| `/devtrail-status` | Verificar estado y cumplimiento de documentación | +| `/straymark-status` | Verificar estado y cumplimiento de documentación | +| `/straymark-new` | Crear cualquier tipo de documento (interactivo) | +| `/straymark-ailog` / `/straymark-aidec` / `/straymark-adr` | Atajos rápidos para AILOG / AIDEC / ADR | +| `/straymark-mcard` / `/straymark-sec` | Flujos interactivos para Model Card / SEC assessment | +| `/straymark-charter-new` | Andamiar un Charter (unidad de trabajo declarativa ex-ante) | +| `/straymark-audit-prompt CHARTER-XX` *(fw-4.9.0+, refactorizada en fw-4.9.0)* | Auditoría externa multi-modelo — escribe prompt unificado en path canónico | +| `/straymark-audit-execute [CHARTER-XX]` *(fw-4.9.0+)* | Corre en una CLI auditora — lee prompt, audita con tool use, escribe report | +| `/straymark-audit-review CHARTER-XX` *(fw-4.9.0+, expandida en fw-4.9.0)* | Consolida N reports en review.md (6 secciones) + mergea YAML en telemetría | + +--- + +## Patrones + +| Patrón | Documento | +|--------|-----------| +| Backlog de follow-ups (registro central + detección de drift) *(fw-4.10.0+)* | [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) | --- -*DevTrail v4.1.0 | [Strange Days Tech](https://strangedays.tech)* +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/00-governance/i18n/es/SPECKIT-CHARTER-BRIDGE.md b/.straymark/00-governance/i18n/es/SPECKIT-CHARTER-BRIDGE.md new file mode 100644 index 0000000..0b536a2 --- /dev/null +++ b/.straymark/00-governance/i18n/es/SPECKIT-CHARTER-BRIDGE.md @@ -0,0 +1,243 @@ +# Puente SpecKit ↔ Charter de StrayMark + +> **Estado**: Patrón empírico (`v0`). Cristaliza tras validarse contra un segundo dominio (Principio #12). Refinar vía PRs cuando surjan nuevos casos de uso. + +## El problema que este documento resuelve + +[SpecKit](https://github.com/StrangeDaysTech/speckit) te da `spec.md`, `plan.md` y `tasks.md` para una feature. StrayMark te da Charters, AILOGs, AIDECs, ADRs. **Ningún documento canónico explicaba cuándo una feature de SpecKit debe producir un Charter, qué granularidad usar, quién dispara la creación, ni cuándo.** Reportado como el artefacto central del [issue #113](https://github.com/StrangeDaysTech/straymark/issues/113) — un *gap* de descubribilidad que llevaba a los agentes (Claude, Gemini, Copilot) a construir modelos mentales binarios (`SpecKit = planeación, StrayMark = audit-trail`) y a descartar silenciosamente la tercera capa (work-as-auditable-shippable-unit) donde viven los Charters. + +Este archivo es la respuesta. + +## Modelo mental + +Tres capas, con *handoffs*: + +| Capa | Vive en | Propósito | Dueño | +|------|---------|-----------|-------| +| **1. Especificación** | `specs/NNN-feature/{spec,plan,tasks,research,quickstart}.md` | Qué es la feature, por qué existe, cómo se implementará a nivel técnico. SpecKit produce esto vía `/speckit-specify` → `/speckit-plan` → `/speckit-tasks`. | Operador (con asistencia del agente). | +| **2. Unidad acotada de ejecución** | `.straymark/charters/NN-slug.md` | El contrato de un único corte enviable de la feature. Empareja el alcance ex-ante (archivos, riesgos, subset de tareas) con la telemetría ex-post (drift, audit, lecciones). | Operador declara el Charter; el agente ejecuta dentro del mismo. | +| **3. Traza de implementación** | `.straymark/07-ai-audit/agent-logs/AILOG-*.md` (más AIDECs y ADRs cuando aplique) | Registro día-a-día de qué se hizo, por qué, con qué nivel de confianza. Cada AILOG referencia al Charter vía `originating_charter:` (o el Charter agrega los AILOGs vía `originating_ailogs:`). | El agente los crea mientras trabaja; el operador revisa. | + +**El puente es el Charter.** Las specs son demasiado de alto nivel para hacer drift-check ("¿enviaste la spec?" no se puede contestar en un horizonte útil). Los AILOGs son demasiado de bajo nivel para enviar contra ellos ("¿enviaste este AILOG?" es la unidad equivocada). Los Charters están en la granularidad correcta: un contrato de alcance estable contra el que puedes auditar en días, no en meses. + +## ¿Cuándo una feature de SpecKit produce un Charter? + +Una feature de SpecKit debe producir **al menos un Charter** cuando *cualquiera* de las siguientes se cumple: + +1. El `tasks.md` de la feature tiene **5 o más tareas** que no puedes completar en una sola sesión. +2. La feature abarca **2 o más fases de SpecKit** (Setup, Foundation, User Stories, Polish, etc.) que pretendes enviar juntas como una unidad. +3. El trabajo amerita una **auditoría externa** (revisión cross-modelo, cross-equipo) al cierre. +4. Quieres **telemetría medible** al cierre (effort estimate vs. real, conteo de drift, lecciones). + +**No** debe producir un Charter cuando: + +- La feature es lo suficientemente pequeña para enviarse en una sola sesión (<1 día, <5 tareas). Usa AILOGs solamente — el overhead del Charter excede la ganancia de auditabilidad. +- La feature es **puramente planeación** (sin código todavía). Espera hasta que exista `tasks.md`; el contrato del Charter necesita tareas concretas que enumerar. +- La feature es **mantenimiento** sin alcance planeado (ej. "arreglar bugs según aparezcan"). Para mantenimiento ad-hoc, los AILOGs son suficientes. + +## Heurísticas de granularidad + +Cuando una feature amerita Charters, elige granularidad por **unidad enviable**, no por unidad estructural. Concretamente: + +### Heurística 1 — Un Charter por corte enviable + +Si la feature tiene Fases (ej. el típico Foundation → US1 → US2 → US3 → Polish de SpecKit), el **primer Charter envuelve el corte de fundación** (todo lo que envía junto como `v0.1`). Charters subsecuentes envuelven cortes subsecuentes. *Effort estimate* **M** es el bucket mediano para un corte enviable; **L** para un corte de feature completa. + +``` +specs/001-peek-mvp-foundation/ +├── spec.md +├── plan.md +└── tasks.md → CHARTER-01 (Foundation: T001-T012, effort M) + CHARTER-02 (peek MVP: T013-T044, effort L) +``` + +### Heurística 2 — NO por User Story + +Las User Stories son demasiado granulares. Una US que toma 2-3 tareas pertenece *dentro* de un Charter, no como su propio Charter. Telemetría por US es ruido; telemetría por corte enviable es señal. + +### Heurística 3 — NO por feature + +Una feature que se envía en dos cortes (ej. MVP → polish) merece dos Charters, no uno. El contrato del Charter contra el que puedes hacer drift-check es "lo que envió este corte", no "lo que eventualmente construimos". + +### Heurística 4 — Caso borde: ≥10 tareas en 4+ fases + +Cuando una feature es excepcionalmente grande, un tercer Charter (o partir el corte de fundación en "scaffolding" + "core") puede estar justificado. Usa effort estimate **L** como tope; si estimarías **XL**, esa es señal de que la feature debe re-especificarse. + +## Cronología de creación + +``` +/speckit-specify → spec.md +/speckit-plan → plan.md +/speckit-tasks → tasks.md + ↓ + ┌────────────────────────────────────────┐ + │ ★ PUNTO DE DECLARACIÓN DEL CHARTER ★ │ + │ │ + │ Operador corre `straymark charter new`│ + │ --from-spec specs/NNN-feature/spec.md│ + │ --type │ + │ │ + │ Status del Charter: declared │ + │ → Operador llena scope, files, tasks │ + │ → status: in-progress al ejecutar │ + └────────────────────────────────────────┘ + ↓ +/speckit-implement → tareas ejecutadas + → AILOGs creados (`originating_charter:` → Charter) + ↓ +straymark charter drift CHARTER-NN → check archivos-vs-commit +straymark charter audit CHARTER-NN → auditoría externa (opcional) +straymark charter close CHARTER-NN → telemetría, status: closed +``` + +**Invariante clave**: declara el Charter *antes* de que `/speckit-implement` arranque. El Charter es un contrato; declararlo después de la ejecución vacía el drift check. + +## Vinculación en frontmatter + +El frontmatter del Charter cita explícitamente la feature de SpecKit: + +```yaml +charter_id: CHARTER-01-workspace-foundation +status: declared +effort_estimate: M +trigger: tasks.md tiene 12 tareas ordenadas en 2 fases; envíar como v0.1. +originating_spec: specs/001-peek-mvp-foundation/spec.md +``` + +La dirección inversa (spec → Charter) es por convención — lista el Charter activo en la sección "Phase 5: Implementation Tracking" de la spec si tu template de `plan.md` la tiene. SpecKit actualmente no tiene un slot de schema para esto; convención emergente. + +Los AILOGs creados durante la ejecución deben citar al Charter: + +```yaml +id: AILOG-2026-05-08-005 +title: T013, T016-T026 — US1 P1 MVP core + TUI + peek bin +agent: claude-code-v4.7 +confidence: high +risk_level: medium +review_required: false +originating_charter: CHARTER-02-peek-mvp-foundation +``` + +## Mapa del ciclo de vida + +| Fase de SpecKit | Evento del Charter | CLI de StrayMark | +|-----------------|-------------------|------------------| +| `/speckit-tasks` completo | **Declarar Charter** | Skill `/straymark-charter-new` o `straymark charter new --from-spec …` | +| Primera tarea inicia | Operador cambia `declared` → `in-progress` | (edición manual de frontmatter) | +| Cada tarea ejecutada | AILOG producido (cuando lo amerite §6 de STRAYMARK.md) | `/straymark-ailog` | +| Decisión mayor encontrada | AIDEC producido | `/straymark-aidec` | +| Cambio arquitectónico | ADR producido | `/straymark-adr` | +| Última tarea hecha, antes de cerrar | Drift check | `straymark charter drift CHARTER-NN` | +| Revisión externa opcional | Auditoría multi-modelo | `straymark charter audit CHARTER-NN` + `/straymark-audit-prompt` + `/straymark-audit-execute` + `/straymark-audit-review` | +| Corte enviado | Cerrar Charter | `straymark charter close CHARTER-NN` (status: `closed`, telemetry yaml emitido) | + +## Mantención del spec durante ejecución multi-Charter + +> **Anclaje empírico**: surfaceado por [issue #150](https://github.com/StrangeDaysTech/straymark/issues/150) después de que Sentinel corriera un único `specs/002-commshub/plan.md` (committed 2026-04-21) a través de **siete Charters consecutivos** (CHARTER-07 a CHARTER-17, ~1 mes). Doce aprendizajes empíricos que impactan materialmente el scope del siguiente Charter **no** quedaron reflejados en el plan. El patrón siguiente codifica lo que Sentinel descubrió antes de llenar CHARTER-18. + +El mapa de ciclo de vida arriba asume **una sola pasada**: los artefactos de SpecKit se generan una vez, luego los Charters se declaran y ejecutan. Esto escala bien para features que producen un solo Charter. Cuando un solo spec conduce varios Charters espaciados por semanas, **los artefactos de planeación driftean respecto al código shippeado** — y re-correr `/speckit-plan` ingenuamente es *peor*, no mejor: la regeneración afirma cosas sobre user stories ya shippeadas que el código real no implementa, y los lectores futuros (auditores, agentes, nuevos operadores) confían en esos artefactos regenerados como ground truth. + +Esta sección responde **cómo**, no **si**: qué disciplina mantiene al spec sincronizado con el código durante ejecución multi-Charter **sin** que el paso de regeneración mienta sobre las partes que ya shippearon. + +### Cuándo refrescar + +Un spec-refresh está justificado cuando *cualquiera* de las siguientes condiciones se cumple: + +1. **≥3 Charters cerrados contra el mismo spec** — el volumen de detalle de ejecución no reflejado es lo suficientemente alto para que las decisiones de scope del siguiente Charter arriesguen heredar premisas obsoletas. +2. **≥4 semanas calendario** desde el último refresh del spec (o desde la generación inicial) y ≥2 Charters cerrados en esa ventana. +3. **Conteo de AILOG `## Risk: R(new, not in Charter)` sobre el spec excede ~6 a través de los Charters cerrados** — la anticipación de riesgo del spec subdescribe medibly el territorio. +4. **La user story del siguiente Charter toca infraestructura que los Charters previos refinaron empíricamente** (nuevas tablas/migraciones creadas, helpers extraídos, contratos cristalizados) y el spec describe el estado pre-refinamiento. + +Si ninguna se cumple y el siguiente Charter apunta a un sub-sistema fresco que los Charters previos no tocaron, **omite el refresh**. La estabilidad del spec tiene valor; refrescar en cada Charter genera churn sin ganancia proporcional de claridad. + +### Cómo refrescar: prompt scope-limited + +**No** re-corras `/speckit-plan` con pizarra en blanco. El `plan.md` + `research.md` + `data-model.md` + `contracts/` + `quickstart.md` regenerados afirmarán cosas sobre user stories ya shippeadas que el código real no implementa. + +En su lugar, invoca `/speckit-plan` con un **prompt scope-limited** que: + +1. **Nombre la fase target explícitamente** (p.ej., "refresca planeación sólo para US5 — failover + tracking"). +2. **Liste secciones bloqueadas que no deben cambiar** (p.ej., "las secciones Foundation, US1, US2, US3, US4 son inmutables — el código shippeado contra ellas es la ground truth, no el plan"). +3. **Cite los AILOGs que documentan refinamientos** (p.ej., "ver AILOG-2026-05-11-043 §R5 para el patrón de reuso de `processed_events`; reflejar esto en el data model refrescado"). +4. **Prohíba regenerar `tasks.md`** — ver subsección siguiente. + +El output es un `plan.md` (y posiblemente `research.md` / `data-model.md` / `contracts/`) donde el contenido de la fase target es fresco y las secciones bloqueadas cargan hacia adelante el estado realmente shippeado, no el estado aspiracional original. + +### Tres gates mecánicos post-refresh + +Antes de mergear el PR del spec-refresh, tres gates corren secuencialmente: + +**Gate (a) — Validación contra realidad del código.** +Para cada entidad no-target-phase en `data-model.md`, diff contra los `db/migrations/*.sql` reales (o fuente equivalente de schema). Para cada endpoint no-target-phase en `contracts/*.md`, diff contra signatures de handlers reales. Cualquier divergencia en una sección *bloqueada* bloquea el merge — eso es la regeneración mintiendo. Los adopters pueden scriptarlo contra su stack; un helper CLI (`straymark spec-drift`) está en el roadmap (ver #150 Ask 3). + +**Gate (b) — Revisión granular hunk-por-hunk del diff.** +Corre `git diff specs/NNN-feature/` y revisa archivo-por-archivo, hunk-por-hunk. Ningún cambio a secciones bloqueadas se acepta sin un comentario de justificación explícito en el PR. El diff es lo suficientemente pequeño cuando es scope-limited para que esto sea factible en una sentada. + +**Gate (c) — Split en dos PRs.** +Aterriza el spec-refresh como su propio PR. Revísalo contra el *código*, no contra el output plan-only. Luego llena el Charter target contra el spec refrescado en un PR *separado*. Mezclar los dos colapsa superficies de review: los reviewers ya no pueden distinguir si un hunk refleja nuevo estado shippeado o nuevo estado planeado. + +### Por qué NO re-correr `/speckit-tasks` mid-ejecución + +El archivo `tasks.md` acumula estado de trace de implementación durante ejecución: checkboxes `[X]` en tareas completadas, anotaciones `*CHARTER-NN: *` citando qué Charter shippeó qué tarea, posiblemente marcadores `^skipped` con rationale. **Regenerar `tasks.md` destruye este estado.** El archivo se vuelve una lista fresca de tareas sin registro de lo que ya shippeó. + +Disciplina: **nunca** re-corras `/speckit-tasks` mientras un spec está en medio de ejecución multi-Charter. En su lugar, **edita manualmente `tasks.md`** sólo para la fase target — añade tareas nuevas para el scope refrescado, deja las secciones ya-shippeadas (`[X]` + anotaciones `*CHARTER-NN:*`) intactas. + +Si descubres que el `tasks.md` original tenía errores en secciones shippeadas (p.ej., una tarea fue incorrectamente marcada `[X]` cuando su trabajo se partió en dos Charters), corrígelo manualmente con un commit Git. Trata `tasks.md` como un registro histórico desde el punto de primera ejecución en adelante; ya no es un artefacto regenerable. + +### Cadencia de re-evaluación de Constitution Check + +El Constitution Check de SpecKit típicamente se corre una vez en tiempo `/speckit-plan`. En ejecución multi-Charter contra un solo spec, la pregunta de *cuándo* re-evaluar queda implícita. Para hacerla explícita: + +- **Por-Charter (recomendado)** — re-evalúa Constitution Check al inicio de cada Charter nuevo declarado contra el spec. El check es barato (leer la constitución; comparar contra el scope declarado del Charter) y atrapa drift temprano, antes de que la ejecución se commitee. +- **Por-spec-refresh (obligatorio cuando el refresh sucede)** — cuando un refresh de `/speckit-plan` scope-limited aterriza, el PR de refresh debe re-correr Constitution Check contra el plan refrescado. Si la versión del framework se movió (p.ej., `fw-4.10.x → fw-4.14.x`), Constitution Check puede arrojar resultados distintos porque existen gates nuevos. +- **NO por-framework-bump aislado** — un `straymark update-framework` entre Charters *no* requiere un re-run inmediato de Constitution Check sobre el spec abierto. El check aplica en el siguiente boundary natural (siguiente declaración de Charter o spec-refresh). + +Codificar esto como cadencia explícita (en lugar de "lo decide quien quiera") cierra una ambigüedad recurrente reportada por Sentinel post-CHARTER-17. + +### Roadmap: `straymark spec-drift` + +Un comando CLI análogo a `straymark charter drift`, pero operando a granularidad de spec — parsear `data-model.md` → entidades → diff contra `db/migrations/*.sql`; parsear `contracts/*.md` → endpoints → diff contra signatures de handlers. Mecanizaría el Gate (a) arriba. + +Diferido deliberadamente a un Charter post-anuncio (tracked por separado). La superficie de CLI es significativa sólo para adopters cuyo formato de spec sigue las convenciones de SpecKit; la capa de detección de lenguaje (handlers Go vs Rust vs TypeScript vs Python; schemas SQL vs ORM-defined) es no-trivial y amerita su propio ciclo de diseño informado por stacks reales de adopters. La disciplina arriba (Gates a/b/c ejecutados manualmente) es el v0; el CLI es el v1 que mecaniza el gate más costoso. + +## Anti-patrones + +**No abras un Charter "por si acaso".** Un Charter sin un corte enviable claro se convierte en una wishlist. El operador termina cerrándolo como `closed: aborted` y la telemetría no significa nada. + +**No abras un Charter por User Story.** Telemetría por US es demasiado ruidosa para informar estimaciones futuras. Agrega. + +**No omitas el campo `originating_spec`.** Aunque el Charter envuelva trabajo que no tiene una spec de SpecKit, define `originating_ailogs:` en su lugar. Charters sin origen son un anti-patrón (señalan motivación no documentada). + +**No corras `straymark charter audit` sin las CLIs auditoras disponibles.** La auditoría es orchestration-only — `straymark` no llama a APIs de LLM. Si no tienes N CLIs auditoras listas, salta el paso; cierra el Charter sin auditoría externa. + +**No cambies status a `closed` antes del drift check + yaml de telemetría.** `straymark charter close` hace ambos atómicamente; el cierre manual salta invariantes. + +**No re-corras `/speckit-tasks` mid-ejecución del spec.** Regenerar `tasks.md` destruye los marcadores `[X]` de completitud y las anotaciones `*CHARTER-NN:* …` que forman el rastro histórico. Ver "Mantención del spec durante ejecución multi-Charter" arriba para la ruta segura (edición manual sólo para la fase target). + +## Cuándo este patrón no aplica + +Este puente asume un flujo de feature manejado por SpecKit con implementación multi-tarea y multi-sesión. No aplica a: + +- **Features de una sola sesión** — usa AILOGs solamente. +- **Trabajo solo de arquitectura, sin implementación** (ej. "diseñar el siguiente schema") — usa ADRs. +- **Refactors puros sin nuevo comportamiento** — usa AILOGs + etiqueta con `refactor:`. +- **Respuesta a incidentes y hotfixes** — usa INC + AILOG. +- **Entregables sólo de cumplimiento** (ej. refresh trimestral del DPIA) — usa el doc type relevante directamente. + +Si tu trabajo encaja en alguno de los anteriores, *no declares Charter*. El costo del Charter excede el valor cuando no hay corte enviable que envolver. + +## Ver también + +- [`EMERGENT-OBSERVATION-DESIGN.md`](EMERGENT-OBSERVATION-DESIGN.md) — el meta-patrón que explica *por qué* el linkeo multi-fuente en este bridge produce observaciones emergentes durante ejecución multi-Charter. +- `STRAYMARK.md` §6 (Cuándo Documentar) y §15 (Charters como unidades acotadas de trabajo) +- `.straymark/templates/charter/charter-template.md` — template declarativo +- `.straymark/templates/charter/charter-telemetry-template.yaml` — template de telemetría +- `.straymark/schemas/charter.schema.v0.json` — JSON Schema del frontmatter declarativo +- `.straymark/schemas/charter-telemetry.schema.v0.json` — JSON Schema de telemetría +- `.claude/skills/straymark-charter-new/SKILL.md` (y equivalentes Gemini / agnóstico) + +> **Contexto empírico citado** (issue #113): Suite Rust CLI/TUI greenfield, onboarding de Claude Opus 4.7 vía los puntos de entrada canónicos (`STRAYMARK.md`, constitución del proyecto, checklist de `CLAUDE.md`, skills `/straymark-*` disponibles, `/straymark-status`). Los Charters fueron *eventualmente* adoptados (2 Charters: foundation + MVP) sólo tras prompt explícito del usuario — confirmando que el gap era sistémico, no específico de la sesión. Este documento elimina ese gap. + +--- + +*Idiomas*: [English](../../SPECKIT-CHARTER-BRIDGE.md) | Español | [简体中文](../zh-CN/SPECKIT-CHARTER-BRIDGE.md) diff --git a/.straymark/00-governance/i18n/es/TC260-IMPLEMENTATION-GUIDE.md b/.straymark/00-governance/i18n/es/TC260-IMPLEMENTATION-GUIDE.md new file mode 100644 index 0000000..4233314 --- /dev/null +++ b/.straymark/00-governance/i18n/es/TC260-IMPLEMENTATION-GUIDE.md @@ -0,0 +1,118 @@ +# Guía de Implementación TC260 — StrayMark + +> Guía práctica para completar un documento TC260RA bajo el **AI Safety Governance Framework v2.0** (TC260, 15-sep-2025). + +**Languages**: [English](../../TC260-IMPLEMENTATION-GUIDE.md) | Español | [简体中文](../zh-CN/TC260-IMPLEMENTATION-GUIDE.md) + +--- + +## Cuándo Crear un TC260RA + +Cree un TC260 Risk Assessment cuando `regional_scope` incluya `china` y se cumpla cualquiera de: + +- El sistema desplegado o modificado es o incluye un modelo de IA. +- La aplicación es para usuarios en China continental, o el operador está incorporado en China continental. +- El sistema tiene flujos de datos transfronterizos que tocan China continental. +- Se anticipa una nueva versión de modelo, escenario, o salto de escala. + +El TC260RA complementa la clasificación EU AI Act en ETH y se referencia vía `related: [TC260RA-...]` desde la ETH / MCARD / AILOG correspondiente. + +--- + +## Los Tres Criterios + +TC260 v2.0 evalúa el riesgo en **tres ejes ortogonales** y los compone en un único nivel (low / medium / high / very_high / extremely_severe). + +### 1. Escenario de Aplicación (`tc260_application_scenario`) + +| Escenario | Ejemplos | Nivel mínimo inherente | +|-----------|----------|------------------------| +| `public_service` | Chatbots gubernamentales | medium | +| `healthcare` | Soporte clínico, imagen médica | high | +| `finance` | Credit scoring, KYC, fraude | high | +| `safety_critical` | Conducción autónoma, control industrial | very_high | +| `content_generation` | Síntesis de texto/imagen/vídeo | medium | +| `social` | Recomendación, ranking, citas | medium | +| `industrial_control` | OT, robótica | very_high | + +### 2. Nivel de Inteligencia (`tc260_intelligence_level`) + +| Nivel | Definición | +|-------|-----------| +| `narrow` | Modelo de propósito único, salida determinista | +| `foundation` | Modelo fundacional general (LLM, visión-lenguaje), sin uso de herramientas | +| `agentic` | Modelo fundacional + uso autónomo de herramientas | +| `general` | Aproximándose a AGI | + +### 3. Escala de Aplicación (`tc260_application_scale`) + +| Escala | Definición | +|--------|-----------| +| `individual` | Usuario único / equipo pequeño | +| `organization` | Una sola organización | +| `societal` | Porción significativa del público (≥ 1M usuarios) | +| `cross_border` | Opera entre China continental y otras jurisdicciones | + +--- + +## Composición del Nivel + +No hay fórmula numérica publicada. Use la matriz como punto de partida y documente el razonamiento. + +| Escenario \ Inteligencia | Narrow | Foundation | Agentic | General | +|--------------------------|--------|-----------|---------|---------| +| public_service | low → medium | medium | high | very_high | +| healthcare / finance | medium | high | high | very_high | +| safety_critical | high | very_high | very_high | extremely_severe | +| content_generation | low | medium | high | very_high | +| social | low | medium | high | very_high | +| industrial_control | high | very_high | very_high | extremely_severe | + +**Modificador por escala**: +- `individual`, `organization` → sin cambio. +- `societal` → sube un nivel. +- `cross_border` → sube un nivel **y** requiere análisis explícito de transferencia transfronteriza (ver PIPL-PIPIA-GUIDE). + +--- + +## Taxonomía de Riesgos + +### Endógenos (`tc260_endogenous_risks`) + +Inherentes al modelo: `hallucination`, `bias`, `robustness`, `data_leakage`, `prompt_injection`, `model_extraction`. + +### De Aplicación (`tc260_application_risks`) + +Del uso técnico: `misuse`, `scope_creep`, `dependency`, `availability`, `integration_flaw`. + +### Derivados (`tc260_derivative_risks`) + +Efectos sociales de segundo orden: `labor_displacement`, `opinion_shaping`, `ecosystem_disruption`, `monoculture`, `loss_of_skill`. + +Para `very_high` y `extremely_severe`, v2.0 requiere explícitamente **monitoreo de riesgo catastrófico**: documente esto en la sección 5 (Medidas de Gobernanza) del TC260RA. + +--- + +## Vinculación desde Otros Documentos + +Cuando se setea `tc260_risk_level: high` (o superior) en un documento que no es TC260RA, la regla **CROSS-004** exige `review_required: true`. El propio TC260RA debe vincularse vía `related:`: + +```yaml +related: + - TC260RA-2026-04-25-001 + - MCARD-2026-04-25-001 + - PIPIA-2026-04-25-001 +``` + +--- + +## Cadencia de Revisión + +| Disparador | Acción | +|-----------|--------| +| Cambio de versión del modelo | Re-ejecutar la sección 4 (contramedidas) | +| Expansión de escenario | Re-clasificar escenario × inteligencia × escala | +| Cruce de tier de escala (ej. 1M usuarios) | Revisión del nivel | +| Actualización regulatoria de TC260 | Revisión completa | + + diff --git a/.straymark/00-governance/i18n/zh-CN/AGENT-RULES.md b/.straymark/00-governance/i18n/zh-CN/AGENT-RULES.md new file mode 100644 index 0000000..1341613 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/AGENT-RULES.md @@ -0,0 +1,385 @@ +# AI 代理规则 - StrayMark + +> 本文档定义了所有 AI 代理在 StrayMark 管理的项目中工作时必须遵循的规则。 + +**语言**: [English](../../AGENT-RULES.md) | [Español](../es/AGENT-RULES.md) | 简体中文 + +--- + +## 1. 强制身份识别 + +### 会话开始时 + +每个代理必须以以下信息进行自我识别： +- 代理名称（例如：`claude-code-v1.0`、`cursor-v1.0`、`gemini-cli-v1.0`） +- 代理版本（如可用） + +### 在每份文档中 + +在 frontmatter 中包含： +```yaml +agent: agent-name-v1.0 +confidence: high | medium | low +``` + +--- + +## 2. 何时需要记录文档 + +### 强制要求 - 创建文档 + +| 场景 | 类型 | 备注 | +|------|------|------| +| 代码复杂度超过阈值 | AILOG | 运行 `straymark analyze --output json`。如果 `summary.above_threshold > 0`，创建 AILOG（默认阈值：8）。**后备方案**：如果 CLI 不可用，应用 >20 行业务逻辑启发式规则 | +| 在 2 个以上技术方案之间做决策 | AIDEC | 记录备选方案 | +| 身份认证/授权/PII 相关变更 | AILOG + ETH | `risk_level: high`，ETH 需要审批 | +| 公共 API 或数据库 Schema 变更 | AILOG | `risk_level: medium+`，考虑 ADR | +| ML 模型或 AI 提示词变更 | AILOG | `risk_level: medium+`，需要人工审查 | +| 与外部服务集成 | AILOG | - | +| 添加/移除/升级安全关键依赖 | AILOG | 需要人工审查 | +| 影响 AI 系统生命周期的变更（部署、退役） | AILOG + ADR | 需要人工审查 | +| OTel 仪表化变更（spans、attributes、pipeline） | AILOG | 标签 `observabilidad`，参见 §9 | +| 实施过程中发现的横向技术债务 | TDE | 参见 §3 "TDE vs `R`（new, not in Charter）" 的判定标准 | + +### 禁止事项 - 不得记录 + +- 凭证、令牌、API 密钥 +- 个人身份信息 +- 任何类型的秘密信息 + +### 可选项 - 无需文档 + +- 格式变更（空格、缩进） +- 拼写纠正 +- 代码注释 +- 次要的样式变更 + +--- + +## 3. 自主权限 + +### 可自由创建 + +| 类型 | 描述 | +|------|------| +| AILOG | 已执行操作的日志 | +| AIDEC | 已做出的技术决策 | + +### 创建草稿 → 需要人工审批 + +| 类型 | 描述 | +|------|------| +| ETH | 伦理审查 | +| ADR | 架构决策 | + +### 提议 → 需要人工验证 + +| 类型 | 描述 | +|------|------| +| REQ | 系统需求 | +| TES | 测试计划 | + +### 创建草稿 → 需要人工审批（新类型） + +| 类型 | 描述 | +|------|------| +| SEC | 安全评估（`review_required: true` 始终为必需） | +| MCARD | 模型/系统卡片（`review_required: true` 始终为必需） | +| DPIA | 数据保护影响评估（`review_required: true` 始终为必需） | + +### 可自由创建（新类型） + +| 类型 | 描述 | +|------|------| +| SBOM | 软件物料清单（事实性清单） | + +### 仅识别 → 人工确定优先级 + +| 类型 | 描述 | +|------|------| +| TDE | 技术债务 | +| INC | 事故总结 | + +### TDE vs `R（new, not in Charter）` + +对于涌现的债务存在两个记录面。它们不可互换——根据工作的生命周期来选择，而不是就手的那一个。 + +**在 AILOG 的 `§Risk` 节中登记一条 `R（new, not in Charter）`**，当该债务： + +- *局限于正在执行的 Charter* 或序列中的下一个 Charter。 +- 可作为已记录的延期、一个小的原子修复，或指向一个已存在的 Charter 的前向引用来解决。 +- 影响为低到中等，且代理可用一条要点描述修复方式。 + +**创建 TDE 文档**，当该债务： + +- 是 *先前 Charter 的遗留*。两种不同形态均符合（均为 TDE-worthy）： + - **严格遗留** —— 先前 Charter 引入了该债务；后续 Charter 仅传播之而不再引入其底层决策（例如：遗留 DB schema 选择；早期 auth 走捷径；延期的 config 决策）。当前 Charter 通过传递接触继承该债务。 + - **模式传播** —— 先前 Charter 设立了某模式，后续 Charter 通过遵循该模式 *再次引入* 之。当前 Charter 不只是传播，而是通过复制模式重新制造同一债务（例如：遗漏 `RequireScope` 的 handler 形态；绕过 HTTP middleware 的测试脚手架）。修复需在模式层面，而非任一个单独 Charter。 +- *横跨多个模块**或 Charter 执行边界*** —— 将其拆分为各 Charter 的 `R` 条目会丢失其架构形态。"Charter 执行边界"涵盖跨会话却未跨代码模块的治理轨迹债务：例如，CHARTER-04 中延期的某项分类，经 CHARTER-08 → CHARTER-13 悄然通过，直至新的 CI gate 才浮现。 +- *需要在当前 scope 包络之外的专用 Charter* 来修复（不是当前 Charter，也不是下一个）。 +- *需要人工决定优先级或分配*，代理无法独自决定（impact × effort 矩阵、所有权、Sprint 安排）。 + +上述四项触发条件即 §2 中 TDE 的激活标准。当你即将编写的 AILOG 中的 `R` 命中上述任一条件时，转而编写 TDE，并在该 AILOG 的 `§Risk` 行中引用它。 + +--- + +## 4. 何时请求人工审查 + +在以下情况下标记 `review_required: true`： + +1. **低置信度**：`confidence: low` +2. **高风险**：`risk_level: high | critical` +3. **安全决策**：任何身份认证/授权相关变更 +4. **不可逆变更**：迁移、删除 +5. **用户影响**：影响用户体验的变更 +6. **伦理问题**：隐私、偏见、无障碍性 +7. **ML 模型变更**：模型参数、架构或训练数据的变更 +8. **AI 提示词变更**：提示词或代理指令的修改 +9. **安全关键依赖**：安全敏感包的添加、移除或升级 +10. **AI 生命周期变更**：AI 系统的部署、退役或主要版本变更 + +--- + +## 5. 文档格式 + +### 使用模板 + +在创建文档之前，加载对应的模板： + +``` +.straymark/templates/TEMPLATE-[TYPE].md +``` + +### 命名规范 + +``` +[TYPE]-[YYYY-MM-DD]-[NNN]-[description].md +``` + +### 存放位置 + +| 类型 | 文件夹 | +|------|--------| +| AILOG | `.straymark/07-ai-audit/agent-logs/` | +| AIDEC | `.straymark/07-ai-audit/decisions/` | +| ETH | `.straymark/07-ai-audit/ethical-reviews/` | +| ADR | `.straymark/02-design/decisions/` | +| REQ | `.straymark/01-requirements/` | +| TES | `.straymark/04-testing/` | +| INC | `.straymark/05-operations/incidents/` | +| TDE | `.straymark/06-evolution/technical-debt/` | +| SEC | `.straymark/08-security/` | +| MCARD | `.straymark/09-ai-models/` | +| SBOM | `.straymark/07-ai-audit/` | +| DPIA | `.straymark/07-ai-audit/ethical-reviews/` | + +### 标签和关联 + +在 frontmatter 中填写 `tags` 和 `related` 字段时： + +**标签（Tags）：** +- 使用 kebab-case 关键词：`sqlite`、`api-design`、`gnome-integration` +- 每个文档 3 到 8 个标签，描述主题、技术或组件 +- 标签支持在 `straymark explore` 中进行搜索和分类 + +**关联（Related）：** +- 仅引用其他 **StrayMark 文档** — 使用文件名加 `.md` 扩展名 +- 如果文档位于 `.straymark/` 的子目录中，包含相对路径：`07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-file.md` +- 如果文档在同一目录中，仅使用文件名即可 +- **不要**在 `related` 中放置任务 ID（T001、US3）、Issue 编号或外部 URL — 请将这些放在文档正文中 + +--- + +## 6. 与人类的沟通 + +### 保持透明 + +- 解释决策背后的推理过程 +- 记录考虑过的备选方案 +- 在存在不确定性时坦诚承认 + +### 保持简洁 + +- 直奔主题 +- 避免不必要的术语 +- 适当使用列表和表格 + +### 保持主动 + +- 识别潜在风险 +- 在明显时建议改进 +- 提醒技术债务 +- **浮现规范源之间的不一致**（原则 #8 —— 参见 [`PRINCIPLES.md`](PRINCIPLES.md)）。当智能体检测到 StrayMark 文档中两个规范源之间的实质性分歧时，必须在继续被询问的任务之前提出。日常工作中应注意的示例： + - 长时间运行的多 Charter 链中 spec 相对于已交付代码的陈旧（参见 [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 1） + - 累积的 `R (new, not in Charter)` 条目符合 TDE 标准但未被升级（参见上文 §3） + - 生效中的 ADR 被当前实现矛盾 + - `§Follow-ups` 计数跨越 backlog-pattern 阈值（参见 [`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md)） + - 关闭后出现需要修订的审计发现（参见 [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 2） + + 参见 [`EMERGENT-OBSERVATION-DESIGN.md`](EMERGENT-OBSERVATION-DESIGN.md) 以了解连接这些表面的元模式。 + +--- + +## 7. 错误处理 + +如果代理犯了错误： + +1. **记录**错误到 AILOG 中 +2. **解释**出了什么问题 +3. **提出**纠正方案 +4. **标记** `review_required: true` + +--- + +## 8. 文档更新 + +### 创建新文档 vs 更新现有文档 + +| 场景 | 操作 | +|------|------| +| 小幅修正 | 更新现有文档 | +| 重大变更 | 创建新文档 | +| 过时文档 | 标记为 `deprecated` | +| 完全替换 | 创建新文档 + 将旧文档标记为 `superseded` | + +### 更新时 + +- 更新 frontmatter 中的 `updated` 字段 +- 如果存在历史记录部分，添加备注 +- 保持与关联文档的一致性 + +--- + +## 9. 可观测性（OpenTelemetry） + +在使用 OpenTelemetry 的项目中工作时： + +### 规则 + +- **不要**在 OTel 属性或日志中捕获 PII、令牌或秘密信息 +- **记录**仪表化管道变更（新 spans、变更的 attributes、Collector 配置）到 AILOG 中，使用标签 `observabilidad` +- 在分布式项目中采用 OTel 时**创建** AIDEC 或 ADR — 记录采用决策和后端选择 +- 当变更涉及 OTel 仪表化时，在 frontmatter 中**设置** `observability_scope` + +### 文档触发条件 + +| 变更 | 文档 | 附加说明 | +|------|------|----------| +| 新 spans 或变更的 attributes | AILOG | 标签 `observabilidad` | +| OTel 后端选择 | AIDEC 或 ADR | 如果是分布式系统 | +| Collector 管道配置 | AILOG | 标签 `observabilidad` | +| 采样策略变更 | AIDEC | 记录理由 | +| 可观测性需求 | REQ | 使用可观测性需求部分 | +| 链路传播测试 | TES | 使用可观测性测试部分 | +| 包含链路证据的事故 | INC | 在时间线中包含 trace_id/span_id | +| 仪表化债务 | TDE | 标签 `observabilidad` | + +--- + +## 10. 架构图（C4 模型） + +在创建涉及架构变更的 ADR 文档时： + +- **包含**适当层级的 Mermaid C4 图 +- **使用** `C4Context` 用于系统级决策（谁使用系统、外部依赖） +- **使用** `C4Container` 用于服务/容器级决策（应用、数据库、消息队列） +- **使用** `C4Component` 用于内部模块决策（服务内的组件） +- **参见** `00-governance/C4-DIAGRAM-GUIDE.md` 获取语法参考和示例 + +> 图表对于次要决策是可选的。当决策改变系统边界、引入新服务或修改服务间通信时使用它们。 + +--- + +## 11. API 规范追踪 + +当变更修改 API 端点时： + +- **验证**相应的 OpenAPI 或 AsyncAPI 规范已更新 +- **引用**规范路径到 AILOG 或 ADR 中，使用 `api_spec_path` 字段（在 REQ 中）或 `api_changes` 字段（在 ADR 中） +- **记录**破坏性 API 变更到 ADR 中，设置 `risk_level: high` + +--- + +## 12. 审计检查点（Charter 工作流） + +在与人共同实现 Charter 时，Agent **主动**在工作流的特定时刻提议外部多模型审计。该检查点是**软性**的——它从不阻塞 `charter close`，也不会升级到强制执行。外部审计在设计上是 opt-in 的（成本，对操作员主要纪律的信任）。 + +### 何时发出检查点 + +当**四个**触发条件同时为真时，**每个 Charter 仅发出一次**检查点： + +1. Charter 处于 `in-progress` 或 `declared` 状态（非 `closed`）。 +2. Charter 的 `## Tasks` 节中所有任务被标记为 `[x]` 已完成（或 Agent 刚完成最后一个）。 +3. `straymark charter drift ` 退出码为 0（无未计入的漂移）。 +4. Developer **尚未**调用 `straymark charter close `，也未提及关闭意图。 + +如果 developer 在同一 Charter 的之前轮次中拒绝了审计，**不要在同一对话的后续轮次中重新发出**。 + +### 检查点消息的形式 + +按以下格式渲染消息（替换 `` 和推荐理由）： + +``` +到达 的检查点。实现已完成，drift check OK， +仅待执行 `straymark charter close`。 + +此时你可以运行外部审计（典型为 2 个不同族的 LLM + 1 个校准器）， +该审计会对实现产出跨模型 findings。 + +我的建议：[是 / 否]，因为： + - <基于 Charter、AILOGs 或 diff 的具体原因> + +如果决定审计： + 运行 /straymark-audit-prompt ，我会将统一审计 prompt + 写入 .straymark/audits//audit-prompt.md。然后在此仓库中 + 打开一个或多个审计员 CLI（gemini-cli、claude-cli、copilot-cli、 + codex-cli），并在每个中调用 /straymark-audit-execute — + 建议：至少 2 个不同模型族的审计员。当且仅当你委托的所有审计员 + 都已完成时，返回此处并运行 /straymark-audit-review 。 + 我会将 N 个 reports 合并为 review.md 文档（含判决、修复计划、 + 审计员评分），并将 YAML 块合并到 Charter 遥测中。 + +如果决定不审计： + 准备好后继续 `straymark charter close `。外部审计 + 完全可选——StrayMark 的声明性 Charter + drift check + AILOG + 纪律已为周期提供了足够严格的关闭信心。 +``` + +### 是/否推荐的启发式 + +这些是启发式，不是硬性规则——你接近上下文，可与 adopter 一起细化。 + +**当满足以下任一条件时推荐"是"**： + +- Charter 触及安全关键面（auth、RLS、secret 处理、IAM）。 +- Charter 引入了 developer 之前未共同实现过的新组件（非重构）。 +- 某关联的 AILOG 记录了 `R`，其 `confidence: low | medium` 且 `risk_level: medium` 或更高。 +- Developer 将 Charter 标记为 `effort_estimate: L` 且这是 adopter 的第一个 Charter。 +- Developer 在 Charter trigger 中**明确**要求跨模型验证。 +- **结构性复杂度信号** *(仅当 CLI 编译启用了 `analyze` feature 时可用，对官方二进制为真)*：`range` 中的 diff 引入或修改了至少一个函数，其认知复杂度超过 `.straymark/config.yml` 中配置的 `complexity.threshold`（默认 `8`）的 **2 倍**（即 ≥ `17`）。一个新的密集函数恰好是两个跨族审计员能捕获 implementation gap、单一模型会遗漏的场景。**优雅降级**：如果二进制缺少 `analyze` feature，静默跳过此信号——不警告，不提及缺失。 + +**当以下条件**全部**满足时推荐"否"**： + +- Charter 是重构或文档变更（无新行为）。 +- `effort_estimate` 为 `XS` 或 `S`。 +- 所有关联 AILOGs 的 `confidence` 均为 `high`，无涌现的 `R` 风险。 +- Charter 的 `risk_level` 为 `low`（或未设置）。 + +**默认情况（无明显信号）**：推荐**"否"**，使用中性措辞（"我没有看到具体信号能正当化两个额外模型的成本；准备好就关闭吧"）。外部审计的成本是真实的——不要靠惯性推荐"是"来虚胖采用。 + +### 行为规则 + +- 检查点在同一 Charter 内一旦 developer 回复就**永不**重复。 +- 检查点**不**阻塞任何后续操作。如果 developer 忽略它并运行 `charter close`，close 正常进行——没有强制执行，将来也不会有（这是 v0+v1 永久设计决策；见 `Propuesta/straymark-audit-skills.md` §2.2）。 +- 检查点**不**计入任何质量度量。`straymark metrics` 中没有"已审计 Charter 百分比"KPI——按设计，避免产生虚胖审计计数的激励。 +- 如果 developer 接受审计，工作流通过三个 skills 依次推进：`/straymark-audit-prompt`（在规范路径写入统一 prompt）→ `/straymark-audit-execute` × N（每个操作员打开的审计员 CLI 一个 — 这些运行在那些 CLI 中，不在主代理中）→ `/straymark-audit-review`（在 `.straymark/audits//review.md` 中内联合并 N 个 reports 并将 YAML 合并到遥测）。操作员从不复制/粘贴 prompts 或 reports — 文件交换通过 `.straymark/audits/` 下的规范路径进行。 + +--- + +## 模式 + +当项目在多个 Charter 之间累积大量 AILOG 且 follow-ups 难以跟踪时,参见 [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) 了解可复制的约定(中央注册表 + drift 检测脚本 + 代理集成)。约 20+ AILOG 的 adopter 会受益;低于该阈值时,仅 per-AILOG 的 `§Follow-ups` 约定就足够了。 + +--- + +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/00-governance/i18n/zh-CN/AI-GOVERNANCE-POLICY.md b/.straymark/00-governance/i18n/zh-CN/AI-GOVERNANCE-POLICY.md new file mode 100644 index 0000000..6eeda34 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/AI-GOVERNANCE-POLICY.md @@ -0,0 +1,321 @@ +# AI 治理政策 + +> **对标标准**：ISO/IEC 42001:2023 — 人工智能管理体系（AIMS） +> +> 本文档为使用 StrayMark 的组织提供治理模板。它将 ISO 42001 条款映射到 StrayMark 文档类型，使团队能够在开发工作流程中构建合规就绪的文档。 +> +> **这是一个模板** — 请根据您组织的实际情况调整各部分内容。 + +--- + +## 1. 范围和背景（ISO 42001 第 4 条） + +> 定义 AI 管理体系的边界和背景。 + +### 1.1 组织背景 + +- **组织**：[组织名称] +- **行业 / 部门**：[部门] +- **范围内的 AI 系统**：[列出本政策涵盖的 AI 系统] +- **排除项**：[明确排除的系统或活动] + +### 1.2 相关方 + +| 相关方 | 需求和期望 | 相关要求 | +|--------|-----------|----------| +| 最终用户 | [期望] | [要求] | +| 监管机构 | [合规期望] | [EU AI Act、GDPR 等] | +| 开发团队 | [期望] | [要求] | +| 管理层 | [期望] | [要求] | +| 数据主体 | [隐私期望] | [GDPR 权利] | + +### 1.3 法律和监管要求 + +| 法规 | 适用性 | 状态 | StrayMark 证据 | +|------|--------|------|---------------| +| EU AI Act | [是/否] | [已合规/进行中/差距] | ETH、MCARD | +| GDPR | [是/否] | [状态] | ETH（数据隐私）、DPIA | +| NIST AI RMF | [是/否] | [状态] | AI-RISK-CATALOG | +| ISO/IEC 42001 | [是/否] | [状态] | 本文档 | +| [其他] | [是/否] | [状态] | [文档] | + +> **StrayMark 映射**：REQ 文档捕获监管要求。ETH 文档评估合规差距。 + +--- + +## 2. 领导力和承诺（ISO 42001 第 5 条） + +> 定义 AI 政策、角色和领导层承诺。 + +### 2.1 AI 政策声明 + +[组织名称] 承诺： + +- 负责任地、合乎道德地开发和部署 AI 系统 +- 确保 AI 辅助决策的透明度和可解释性 +- 保护受影响人员的隐私和基本权利 +- 维持对 AI 系统的人工监督 +- 持续改进 AI 治理实践 + +### 2.2 角色和职责 + +| 角色 | 职责 | StrayMark 映射 | +|------|------|---------------| +| AI 治理负责人 | 整体 AIMS 管理、政策维护 | 本文档、MANAGEMENT-REVIEW-TEMPLATE | +| 开发团队 | 文档编写、实施、测试 | AILOG、AIDEC、TES | +| AI 伦理审查员 | 伦理审查和审批 | ETH 审批 | +| 风险管理者 | 风险识别和评估 | AI-RISK-CATALOG、ETH | +| 数据保护官 | 隐私合规、DPIA 监督 | DPIA、ETH（数据隐私） | +| AI 代理 | 在定义的限制范围内自主编写文档 | 遵循 AGENT-RULES.md 自主权表 | + +### 2.3 管理层承诺 + +- [ ] AI 政策已批准并传达 +- [ ] 角色和职责已分配 +- [ ] 已为 AI 治理分配资源 +- [ ] 已安排定期管理评审 + +> **StrayMark 映射**：ADR 文档记录治理决策。AGENT-RULES.md 定义代理自主权限。 + +--- + +## 3. 风险规划（ISO 42001 第 6 条） + +> 识别风险、设定目标并规划变更。 + +### 3.1 风险识别 + +| 风险类别 | 描述 | 可能性 | 影响 | 当前控制措施 | StrayMark 证据 | +|----------|------|--------|------|-------------|---------------| +| 偏见 / 公平性 | [描述] | [高/中/低] | [高/中/低] | [控制措施] | ETH（偏见部分） | +| 隐私 | [描述] | [高/中/低] | [高/中/低] | [控制措施] | ETH（隐私）、DPIA | +| 安全 | [描述] | [高/中/低] | [高/中/低] | [控制措施] | SEC | +| 安全性 | [描述] | [高/中/低] | [高/中/低] | [控制措施] | ETH、REQ（安全性） | +| 透明度 | [描述] | [高/中/低] | [高/中/低] | [控制措施] | ETH（透明度） | +| 环境 | [描述] | [高/中/低] | [高/中/低] | [控制措施] | ETH（环境影响） | + +> **参考**：完整的风险目录映射到 NIST AI 600-1 类别，请参见 AI-RISK-CATALOG.md。 +> +> **StrayMark 映射**：ETH 文档评估个别风险。AI-RISK-CATALOG.md 按照 ISO 42001 附录 A.5 整合组织风险登记表。 + +### 3.2 AI 目标 + +| 目标 | 指标 | 衡量方法 | 时间线 | 负责人 | +|------|------|----------|--------|--------| +| 文档覆盖率 | [例如：100% 的重大变更已记录] | `straymark metrics` | [日期] | [负责人] | +| 审查合规性 | [例如：所有高风险文档在 5 天内审查] | `straymark metrics` | [日期] | [负责人] | +| 风险评估覆盖率 | [例如：所有高风险变更均有 ETH] | `straymark compliance` | [日期] | [负责人] | + +### 3.3 变更规划 + +当重大变更影响 AI 管理体系时： + +1. 在 **ADR** 中记录变更决策 +2. 在 **ETH** 文档中评估风险 +3. 如果治理范围发生变化，更新本政策 +4. 向所有相关方传达变更信息 + +--- + +## 4. 支持和资源（ISO 42001 第 7 条） + +> 定义资源、能力和沟通方式。 + +### 4.1 资源 + +| 资源 | 描述 | 状态 | +|------|------|------| +| StrayMark 框架 | 文档治理系统 | [已安装/版本] | +| StrayMark CLI | 自动化和验证工具 | [版本] | +| AI 代理平台 | [Claude、Gemini、Copilot、Cursor] | [已配置] | +| 培训 | 团队 AI 治理培训 | [状态] | + +### 4.2 能力要求 + +| 角色 | 所需能力 | 培训计划 | +|------|----------|----------| +| 开发人员 | StrayMark 使用、AI 伦理基础、监管意识 | [计划] | +| AI 代理 | AGENT-RULES.md 合规、模板使用 | [指令配置] | +| 审查员 | 风险评估、EU AI Act 要求、ISO 42001 基础 | [计划] | + +### 4.3 意识 + +所有团队成员必须了解： +- 本 AI 治理政策 +- AGENT-RULES.md 和文档要求 +- PRINCIPLES.md 和伦理准则 +- 其在 AI 管理体系中的角色 + +### 4.4 沟通 + +| 内容 | 对象 | 时间 | 方式 | StrayMark 记录 | +|------|------|------|------|---------------| +| 政策更新 | 全体团队 | 变更时 | [方式] | ADR | +| 风险评估 | 审查员 | 每次创建 ETH 时 | StrayMark 通知 | ETH | +| 事故报告 | 管理层 | 24 小时内 | [方式] | INC | +| 治理指标 | 管理层 | [每月/每季度] | `straymark metrics` | 指标报告 | + +### 4.5 文档化信息 + +StrayMark 作为 AIMS 的文档化信息系统。关键文档： + +| ISO 42001 要求 | StrayMark 文档 | +|----------------|---------------| +| AI 政策 | 本文档（§2） | +| 风险评估 | ETH、AI-RISK-CATALOG.md | +| 运营程序 | AGENT-RULES.md、DOCUMENTATION-POLICY.md | +| 变更记录 | AILOG（所有变更） | +| 决策记录 | AIDEC、ADR | + +--- + +## 5. AI 生命周期运营（ISO 42001 第 8 条） + +> 定义 AI 系统在其生命周期中的管理方式。 + +### 5.1 生命周期阶段 + +| 阶段 | 活动 | StrayMark 文档 | ISO 42001 控制 | +|------|------|---------------|----------------| +| 设计 | 需求、架构决策 | REQ、ADR、AIDEC | A.6.2.2 | +| 开发 | 实施、代码变更 | AILOG、AIDEC | A.6.2.2、A.6.2.9 | +| 测试 | 验证、确认 | TES | A.6.2.3、A.6.2.4 | +| 部署 | 发布、配置 | AILOG | A.6.2.5 | +| 监控 | 运营、可观测性 | AILOG、INC | A.6.2.6 | +| 退役 | 下线 | ADR、AILOG | A.6.2.7 | + +> **参考**：系统生命周期状态跟踪请参见 AI-LIFECYCLE-TRACKER.md。 + +### 5.2 文档要求 + +根据 AGENT-RULES.md，以下情况需要文档： + +- 影响身份认证/授权/PII 的变更 → AILOG + ETH 草稿 +- 公共 API 或数据库 Schema 变更 → AILOG +- ML 模型或 AI 提示词变更 → AILOG + 人工审查 +- 代码超过认知复杂度阈值（运行 `straymark analyze`；后备方案：>20 行）→ AILOG +- 在 2 个以上方案之间做决策 → AIDEC +- 安全关键依赖变更 → AILOG + 人工审查 + +### 5.3 第三方 AI 组件 + +| 组件 | 供应商 | 用途 | 风险级别 | 上次审查 | +|------|--------|------|----------|----------| +| [组件] | [供应商] | [用途] | [高/中/低] | [日期] | + +> **StrayMark 映射**：SBOM 记录 AI 供应链。ETH 评估第三方风险。 + +--- + +## 6. 绩效评估（ISO 42001 第 9 条） + +> 定义治理绩效的监控和评审方式。 + +### 6.1 监控和测量 + +| KPI | 目标 | 衡量方法 | 频率 | +|-----|------|----------|------| +| 文档覆盖率 | [目标百分比] | `straymark metrics` | [频率] | +| 审查完成率 | [目标百分比] | `straymark metrics` | [频率] | +| 平均文档编写时间 | [目标天数] | `straymark metrics` | [频率] | +| 高风险文档审查时间 | [目标天数] | 手动跟踪 | [频率] | +| 事故文档化 | [目标百分比] | INC 数量与事故数比较 | [频率] | + +> **参考**：详细 KPI 定义请参见 AI-KPIS.md。 + +### 6.2 内部审计 + +- **频率**：[例如：每季度] +- **范围**：本政策、AGENT-RULES.md 和监管要求的合规性 +- **方法**：`straymark compliance --all` + 人工审查 +- **审计员**：[角色/姓名] + +### 6.3 管理评审 + +- **频率**：[例如：每季度] +- **输入**：治理指标、审计结果、事故报告、风险评估 +- **输出**：政策更新、资源决策、改进行动 + +> **参考**：评审议程模板请参见 MANAGEMENT-REVIEW-TEMPLATE.md。 + +--- + +## 7. 持续改进（ISO 42001 第 10 条） + +> 定义不符合项的处理方式和改进驱动机制。 + +### 7.1 不符合项和纠正措施 + +当发现不符合项时： + +1. **记录**不符合项（INC 或带有 `risk_level: high` 的 AILOG） +2. **评估**根本原因和影响 +3. **实施**纠正措施 +4. **验证**有效性 +5. 如需要则**更新**治理文档（政策变更使用 ADR） + +### 7.2 改进来源 + +| 来源 | StrayMark 输入 | 行动 | +|------|---------------|------| +| 验证失败 | `straymark validate` 错误 | 修复并记录 | +| 合规差距 | `straymark compliance` 报告 | 规划补救措施 | +| 事故复盘 | INC 文档 | 实施纠正措施 | +| 管理评审 | 评审会议输出 | 更新政策/目标 | +| 代理反馈 | 带建议的 AILOG | 评估并确定优先级 | +| 监管变更 | 外部监控 | 更新模板和政策 | + +--- + +## 附录：ISO 42001 附录 A 控制 → StrayMark 映射 + +> 此映射使团队能够通过 StrayMark 文档证明附录 A 控制的覆盖情况。 + +| 主题领域 | 控制 | ID | StrayMark 文档 | +|----------|------|-----|---------------| +| **A.2 AI 政策** | AI 政策 | A.2.2 | 本文档 §2 | +| | 负责任的 AI 议题 | A.2.3 | 本文档 §2、PRINCIPLES.md | +| **A.3 内部组织** | 角色和职责 | A.3.2 | 本文档 §2、AGENT-RULES.md | +| | AI 问题报告 | A.3.3 | INC、ETH | +| | 组织变更的影响 | A.3.4 | ADR | +| **A.4 资源** | 资源 | A.4.2 | 本文档 §4 | +| | 能力 | A.4.3 | 本文档 §4 | +| | 负责任使用意识 | A.4.4 | PRINCIPLES.md、代理指令 | +| | 咨询 | A.4.5 | MANAGEMENT-REVIEW-TEMPLATE | +| | AI 系统相关沟通 | A.4.6 | ADR、REQ | +| **A.5 影响评估** | 风险评估 | A.5.2 | ETH、AI-RISK-CATALOG | +| | 影响评估 | A.5.3 | ETH、DPIA | +| | 影响文档 | A.5.4 | ETH、DPIA | +| **A.6 AI 系统生命周期** | 设计和开发 | A.6.2.2 | ADR、AIDEC | +| | AI 模型训练和测试 | A.6.2.3 | MCARD、TES | +| | 验证和确认 | A.6.2.4 | TES | +| | 部署 | A.6.2.5 | AILOG、AI-LIFECYCLE-TRACKER | +| | 运营和监控 | A.6.2.6 | AILOG、AI-LIFECYCLE-TRACKER、OBSERVABILITY-GUIDE | +| | 退役 | A.6.2.7 | AI-LIFECYCLE-TRACKER、ADR | +| | 负责任的集成 | A.6.2.8 | ADR、AIDEC | +| | 文档化 | A.6.2.9 | AILOG（所有变更已记录） | +| | 定义的使用和误用 | A.6.2.10 | MCARD | +| | 第三方组件 | A.6.2.11 | SBOM | +| **A.7 AI 数据** | 开发数据 | A.7.2 | MCARD | +| | ML 数据质量 | A.7.3 | MCARD | +| | 数据准备 | A.7.4 | MCARD | +| | 数据获取 | A.7.5 | SBOM、DPIA | +| | 数据溯源 | A.7.6 | SBOM | +| **A.8 向相关方提供的信息** | AI 交互透明度 | A.8.2 | ETH（透明度） | +| | AI 输出信息 | A.8.3 | ETH（可解释性） | +| | 信息获取 | A.8.4 | REQ、ADR | +| | 支持人工操作 | A.8.5 | AGENT-RULES.md（人工审查触发条件） | +| **A.9 AI 系统使用** | 负责任使用目标 | A.9.2 | 本文档 §5、PRINCIPLES.md | +| | 预期用途 | A.9.3 | MCARD、REQ | +| | 负责任使用流程 | A.9.4 | DOCUMENTATION-POLICY.md、AGENT-RULES.md | +| | 人工监督 | A.9.5 | AGENT-RULES.md（自主权表） | +| **A.10 第三方** | AI 组件供应商 | A.10.2 | SBOM | +| | 共享 ML 模型 | A.10.3 | SBOM | +| | 向第三方提供 | A.10.4 | ETH、MCARD | + +--- + +*AI 治理政策模板 — StrayMark 框架* +*对标 ISO/IEC 42001:2023* + + diff --git a/.straymark/00-governance/i18n/zh-CN/AI-KPIS.md b/.straymark/00-governance/i18n/zh-CN/AI-KPIS.md new file mode 100644 index 0000000..62de332 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/AI-KPIS.md @@ -0,0 +1,186 @@ +# AI 治理 KPI + +> **对标标准**：ISO/IEC 42001:2023 第 9 条 — 绩效评估 +> +> 本文档定义了衡量 AI 管理体系有效性的关键绩效指标（KPI）。这些指标为管理评审（第 9.3 条）和内部审计（第 9.2 条）提供客观证据，并支持持续改进（第 10 条）。 +> +> **这是一个模板** — 请根据您组织的成熟度和实际情况调整目标和衡量方法。 + +--- + +## 1. 目的 + +KPI 在 AI 管理体系中发挥三项功能： + +- **监控**：跟踪治理健康状况并及早发现退化 +- **问责**：为审计和评审提供合规性的客观证据 +- **改进**：识别趋势和需要纠正措施的领域 + +> **StrayMark 映射**：使用 `straymark metrics` 进行自动化 KPI 收集。结果输入到 MANAGEMENT-REVIEW-TEMPLATE.md 用于定期评审。 + +--- + +## 2. KPI 定义 + +### KPI-01：文档覆盖率 + +| 字段 | 值 | +|------|-----| +| **KPI 名称** | 文档覆盖率 | +| **描述** | 具有关联 StrayMark 文档（AILOG、AIDEC、ETH 等）的 AI 相关变更的百分比。 | +| **目标** | > 80% | +| **当前值** | [测量值] | +| **衡量方法** | `straymark metrics` — 已记录变更与 AI 相关提交总数的比率 | +| **频率** | 每月 | +| **负责人** | [开发团队负责人] | +| **ISO 42001 参考** | 第 9.1 条（监控、测量、分析和评估） | + +> **指导**：从切合实际的基线开始。新使用 StrayMark 的团队可以初始目标设为 50%，每季度增加 10%。需要记录文档的变更在 AGENT-RULES.md 中定义。 + +--- + +### KPI-02：审查合规率 + +| 字段 | 值 | +|------|-----| +| **KPI 名称** | 审查合规率 | +| **描述** | 需要人工审查的文档中，在规定时间内完成审查的百分比。 | +| **目标** | 100% | +| **当前值** | [测量值] | +| **衡量方法** | `straymark metrics` — 已审查文档与标记为需要审查的文档的比率 | +| **频率** | 每月 | +| **负责人** | [AI 伦理审查员] | +| **ISO 42001 参考** | 第 9.1 条（监控、测量、分析和评估） | + +> **指导**：需要审查的文档包括：ETH 文档、带有 `risk_level: high` 或 `risk_level: critical` 的 AILOG 条目，以及根据 AGENT-RULES.md 影响身份认证/PII 的变更。 + +--- + +### KPI-03：平均文档编写时间 + +| 字段 | 值 | +|------|-----| +| **KPI 名称** | 平均文档编写时间 | +| **描述** | 从代码变更到创建相应 AILOG 条目之间的平均天数。 | +| **目标** | < 1 天 | +| **当前值** | [测量值] | +| **衡量方法** | 比较 git 提交时间戳与文档头部中的 AILOG 创建日期 | +| **频率** | 每月 | +| **负责人** | [开发团队负责人] | +| **ISO 42001 参考** | 第 9.1 条（监控、测量、分析和评估） | + +> **指导**：AI 代理应在与变更相同的会话中创建文档，目标为 0 天。人工编写的文档不应超过 2 个工作日。 + +--- + +### KPI-04：风险分布 + +| 字段 | 值 | +|------|-----| +| **KPI 名称** | 风险分布 | +| **描述** | AI-RISK-CATALOG 中高风险和关键风险条目与总条目的比率。 | +| **目标** | < 20% high/critical | +| **当前值** | [测量值] | +| **衡量方法** | `straymark metrics` — 风险评分 >= 10 的数量除以总风险数 | +| **频率** | 每季度 | +| **负责人** | [风险管理者] | +| **ISO 42001 参考** | 第 6 条（规划 — 应对风险和机遇的措施） | + +> **指导**：关键风险比例过高表明控制措施不成熟或风险识别过于激进。无论哪种情况，都需要管理层关注。跟踪趋势变化而非绝对值。 + +--- + +### KPI-05：事故响应时间 + +| 字段 | 值 | +|------|-----| +| **KPI 名称** | 事故响应时间 | +| **描述** | 从事故发现到在 StrayMark 中创建相应 INC 文档的时间。 | +| **目标** | < 24 小时 | +| **当前值** | [测量值] | +| **衡量方法** | 比较事故发现时间戳（来自监控/告警）与 INC 文档创建日期 | +| **频率** | 每次事故（每季度汇总） | +| **负责人** | [运营负责人] | +| **ISO 42001 参考** | 第 10.1 条（不符合项和纠正措施） | + +> **指导**：这衡量的是文档化响应，而非问题解决。更快的文档化能实现更快的根本原因分析并防止知识丢失。高严重性事故的目标应更严格。 + +--- + +### KPI-06：合规评分 + +| 字段 | 值 | +|------|-----| +| **KPI 名称** | 合规评分 | +| **描述** | StrayMark 合规验证引擎衡量的总体监管合规百分比。 | +| **目标** | > 75% | +| **当前值** | [测量值] | +| **衡量方法** | `straymark compliance --all` — 所有适用法规中通过规则的百分比 | +| **频率** | 每季度 | +| **负责人** | [AI 治理负责人] | +| **ISO 42001 参考** | 第 9.2 条（内部审计） | + +> **指导**：合规引擎检查文档完整性、必填字段、审查状态和监管映射。低于 50% 的分数表明存在需要立即补救规划的重大差距。 + +--- + +## 3. KPI 摘要仪表板 + +| KPI | 目标 | 当前值 | 趋势 | 状态 | +|-----|------|--------|------|------| +| 文档覆盖率 | > 80% | [值] | [上升/下降/稳定] | [达标 / 有风险 / 未达标] | +| 审查合规率 | 100% | [值] | [上升/下降/稳定] | [达标 / 有风险 / 未达标] | +| 平均文档编写时间 | < 1 天 | [值] | [上升/下降/稳定] | [达标 / 有风险 / 未达标] | +| 风险分布 | < 20% high/critical | [值] | [上升/下降/稳定] | [达标 / 有风险 / 未达标] | +| 事故响应时间 | < 24 小时 | [值] | [上升/下降/稳定] | [达标 / 有风险 / 未达标] | +| 合规评分 | > 75% | [值] | [上升/下降/稳定] | [达标 / 有风险 / 未达标] | + +--- + +## 4. 衡量时间表 + +| 活动 | 频率 | 负责人 | 输出 | +|------|------|--------|------| +| 运行 `straymark metrics` | 每月 | [开发团队负责人] | 更新的 KPI 值 | +| 运行 `straymark compliance --all` | 每季度 | [AI 治理负责人] | 合规评分 | +| 更新 KPI 摘要仪表板 | 每月 | [AI 治理负责人] | 本文档（第 3 节） | +| 管理评审中审查 KPI | 每季度 | [管理层] | MANAGEMENT-REVIEW-TEMPLATE | +| 重新评估目标 | 每年 | [AI 治理负责人] | 本文档中更新的目标 | + +--- + +## 5. 添加自定义 KPI + +组织可以定义额外的 KPI。请使用以下模板： + +### KPI-NN：[KPI 名称] + +| 字段 | 值 | +|------|-----| +| **KPI 名称** | [名称] | +| **描述** | [此 KPI 衡量的内容] | +| **目标** | [目标值] | +| **当前值** | [测量值] | +| **衡量方法** | [如何衡量] | +| **频率** | [多久一次] | +| **负责人** | [负责人] | +| **ISO 42001 参考** | [适用条款] | + +--- + +## 6. ISO 42001 第 9 条映射 + +| 条款 | 要求 | KPI 覆盖 | +|------|------|----------| +| 9.1 | 监控、测量、分析和评估 | KPI-01、KPI-02、KPI-03 | +| 9.2 | 内部审计 | KPI-06（合规评分） | +| 9.3 | 管理评审 | 所有 KPI 输入到 MANAGEMENT-REVIEW-TEMPLATE | +| 6.1 | 应对风险和机遇的措施 | KPI-04（风险分布） | +| 10.1 | 不符合项和纠正措施 | KPI-05（事故响应时间） | + +--- + +*AI 治理 KPI 模板 — StrayMark 框架* +*对标 ISO/IEC 42001:2023 第 9 条* + + diff --git a/.straymark/00-governance/i18n/zh-CN/AI-LIFECYCLE-TRACKER.md b/.straymark/00-governance/i18n/zh-CN/AI-LIFECYCLE-TRACKER.md new file mode 100644 index 0000000..c8a892b --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/AI-LIFECYCLE-TRACKER.md @@ -0,0 +1,222 @@ +# AI 系统生命周期追踪器 + +> **对标标准**：ISO/IEC 42001:2023 附录 A.6 — AI 系统生命周期 +> +> 本文档追踪所有纳入治理范围的 AI 系统在其生命周期各阶段的状态。它提供了每个系统当前状态、所有权和合规状态的可见性，使团队能够管理过渡并确保在每个阶段实施适当的控制措施。 +> +> **这是一个模板** — 请注册您组织的 AI 系统，并在其经历生命周期各阶段时进行更新。 + +--- + +## 1. AI 系统清单 + +| 系统名称 | 类型 | 当前阶段 | 版本 | 负责人 | 上次审查日期 | 风险级别 | +|----------|------|----------|------|--------|-------------|----------| +| Acme Sentiment Classifier | Classifier (NLP) | 监控 | 2.1.0 | [ML 团队负责人] | [YYYY-MM-DD] | Medium | +| [系统名称] | [LLM / Classifier / Recommender / Agent / Other] | [阶段] | [版本] | [负责人] | [日期] | [Low / Medium / High / Critical] | + +> **StrayMark 映射**：每个系统应有对应的 ETH、MCARD 和 AILOG 文档。使用 `straymark status` 验证文档覆盖情况。 + +--- + +## 2. 生命周期阶段定义 + +> 每个阶段映射到 ISO 42001 附录 A.6.2 控制。以下清单定义了系统过渡到下一阶段之前的最低要求。 + +### 阶段 1：设计（ISO 42001 A.6.2.2） + +> 在开发开始之前定义需求、架构和初始风险评估。 + +- [ ] 系统目的和预期用途已记录（REQ） +- [ ] 架构决策已记录（ADR 或 AIDEC） +- [ ] 初始风险评估已完成（ETH） +- [ ] 数据需求已确定 +- [ ] 成功标准和指标已定义 +- [ ] 利益相关者和受影响方已确定 +- [ ] 监管要求已映射（REQ） + +| StrayMark 证据 | 文档类型 | +|---------------|----------| +| 需求规格说明 | REQ | +| 架构决策 | ADR、AIDEC | +| 初始风险评估 | ETH | + +--- + +### 阶段 2：训练和测试（ISO 42001 A.6.2.3） + +> 使用质量保证的数据和偏见评估来构建、训练和测试 AI 模型。 + +- [ ] 训练数据质量已验证并记录 +- [ ] 数据溯源已记录（SBOM） +- [ ] 偏见评估已完成（ETH — 偏见部分） +- [ ] 模型卡片已创建（MCARD） +- [ ] 训练配置已记录 +- [ ] 初始性能基准已记录 +- [ ] 数据隐私评估已完成（如适用则需要 DPIA） + +| StrayMark 证据 | 文档类型 | +|---------------|----------| +| 数据质量评估 | MCARD | +| 偏见评估 | ETH | +| 模型文档 | MCARD | +| 数据溯源 | SBOM | + +--- + +### 阶段 3：验证和确认（ISO 42001 A.6.2.4） + +> 执行测试计划，根据需求进行验证，并确认系统满足定义的标准。 + +- [ ] 测试计划已执行并记录结果（TES） +- [ ] 性能指标达到定义的目标 +- [ ] 跨人口统计群体评估了公平性指标 +- [ ] 安全测试已完成（对抗性输入、提示词注入） +- [ ] 边界情况和故障模式分析已完成 +- [ ] 可解释性评估已通过 +- [ ] 指定审查员已签字确认 + +| StrayMark 证据 | 文档类型 | +|---------------|----------| +| 测试结果 | TES | +| 安全评估 | ETH（安全部分） | +| 审查员批准 | ETH（批准） | + +--- + +### 阶段 4：部署（ISO 42001 A.6.2.5） + +> 将系统发布到生产环境，配置监控、回滚计划和运营文档。 + +- [ ] 部署计划已记录 +- [ ] 监控和告警已配置 +- [ ] 回滚计划已定义并测试 +- [ ] 用户文档或信息披露已准备 +- [ ] 人工监督机制已到位 +- [ ] 事故响应程序已定义 +- [ ] 部署已记录（AILOG） + +| StrayMark 证据 | 文档类型 | +|---------------|----------| +| 部署记录 | AILOG | +| 监控设置 | AILOG | +| 回滚计划 | ADR | + +--- + +### 阶段 5：运营和监控（ISO 42001 A.6.2.6） + +> 在生产环境中持续监控系统性能、数据漂移和合规性。 + +- [ ] SLO 已定义并跟踪 +- [ ] 数据漂移监控已启动 +- [ ] 模型性能根据基线进行跟踪 +- [ ] 事故响应程序已激活 +- [ ] 定期合规检查已安排 +- [ ] 用户反馈收集机制已到位 +- [ ] 定期风险重新评估已安排 + +| StrayMark 证据 | 文档类型 | +|---------------|----------| +| 性能日志 | AILOG | +| 事故 | INC | +| 风险重新评估 | ETH | +| 合规检查 | `straymark compliance` | + +--- + +### 阶段 6：退役（ISO 42001 A.6.2.7） + +> 安全地下线系统，妥善处理数据并通知利益相关者。 + +- [ ] 退役决策已记录（ADR） +- [ ] 利益相关者和受影响方已通知 +- [ ] 数据已按保留政策存档或处置 +- [ ] 模型制品已存档或删除 +- [ ] API 端点已在适当的通知期内弃用 +- [ ] 替代系统已记录（如适用） +- [ ] 最终状态已在本追踪器中记录 + +| StrayMark 证据 | 文档类型 | +|---------------|----------| +| 退役决策 | ADR | +| 最终状态更新 | AILOG | +| 数据处置记录 | AILOG | + +--- + +## 3. 示例：Acme Sentiment Classifier + +> 预填示例，展示一个处于监控阶段的系统。 + +### 系统详情 + +| 字段 | 值 | +|------|-----| +| **系统名称** | Acme Sentiment Classifier | +| **类型** | Classifier (NLP) | +| **当前阶段** | 运营和监控 | +| **版本** | 2.1.0 | +| **负责人** | ML Team Lead | +| **风险级别** | Medium | +| **部署日期** | 2025-09-15 | +| **上次审查** | [YYYY-MM-DD] | +| **下次审查** | [YYYY-MM-DD] | + +### 阶段完成历史 + +| 阶段 | 已完成 | 日期 | 关键文档 | +|------|--------|------|----------| +| 设计 | 是 | 2025-03-10 | REQ-001、ADR-012、ETH-008 | +| 训练/测试 | 是 | 2025-06-20 | MCARD-003、ETH-008（已更新） | +| 验证/确认 | 是 | 2025-08-05 | TES-015、TES-016 | +| 部署 | 是 | 2025-09-15 | AILOG-042 | +| 运营/监控 | 进行中 | — | AILOG-050、INC-003 | +| 退役 | — | — | — | + +### 当前监控状态 + +| 指标 | 目标 | 当前值 | 状态 | +|------|------|--------|------| +| 准确率 | > 92% | 94.1% | 达标 | +| 公平性（人口统计均等性） | < 5% 差距 | 3.2% 差距 | 达标 | +| 延迟（p95） | < 200ms | 145ms | 达标 | +| 数据漂移评分 | < 0.15 | 0.08 | 达标 | + +--- + +## 4. 阶段过渡审批 + +> 记录每次阶段过渡所需的审批。 + +| 过渡 | 所需审批人 | 审批方式 | +|------|-----------|----------| +| 设计到训练/测试 | [系统负责人] | AIDEC 或 ADR | +| 训练/测试到验证 | [ML 团队负责人] | MCARD 完成 | +| 验证到部署 | [AI 伦理审查员 + 系统负责人] | ETH 批准 + TES 通过 | +| 部署到监控 | [运营负责人] | 部署 AILOG | +| 任何阶段到退役 | [AI 治理负责人 + 管理层] | 带说明的 ADR | + +--- + +## 5. ISO 42001 附录 A.6 控制摘要 + +| 控制 | 描述 | 生命周期阶段 | StrayMark 证据 | +|------|------|-------------|---------------| +| A.6.2.2 | AI 系统设计和开发 | 设计、开发 | ADR、AIDEC、REQ | +| A.6.2.3 | AI 模型训练和测试 | 训练/测试 | MCARD、TES | +| A.6.2.4 | 验证和确认 | 验证 | TES | +| A.6.2.5 | AI 系统部署 | 部署 | AILOG | +| A.6.2.6 | 运营和监控 | 监控 | AILOG、INC | +| A.6.2.7 | AI 系统退役 | 退役 | ADR、AILOG | +| A.6.2.8 | AI 的负责任集成 | 所有阶段 | ADR、AIDEC | +| A.6.2.9 | AI 系统文档化 | 所有阶段 | AILOG（所有变更） | +| A.6.2.10 | 定义的使用和误用 | 设计、部署 | MCARD、REQ | +| A.6.2.11 | 第三方 AI 组件 | 所有阶段 | SBOM | + +--- + +*AI 系统生命周期追踪器模板 — StrayMark 框架* +*对标 ISO/IEC 42001:2023 附录 A.6* + + diff --git a/.straymark/00-governance/i18n/zh-CN/AI-RISK-CATALOG.md b/.straymark/00-governance/i18n/zh-CN/AI-RISK-CATALOG.md new file mode 100644 index 0000000..c5fda4b --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/AI-RISK-CATALOG.md @@ -0,0 +1,202 @@ +# AI 风险目录 + +> **对标标准**：NIST AI 600-1 和 ISO/IEC 42001:2023 附录 C +> +> 本文档为 StrayMark 管理下的 AI 系统提供集中的风险登记表。它将风险条目映射到 NIST AI 600-1 的 12 个风险类别，并与 ISO 42001 附录 A.5（AI 系统影响评估）和 ISO/IEC 23894（AI 风险管理）保持一致。 +> +> **这是一个模板** — 请填入您组织 AI 系统的具体风险。 + +--- + +## 1. 目的 + +本风险目录作为组织内所有 AI 相关风险的唯一信息来源。它支持： + +- **集中追踪**所有已识别的 AI 风险 +- **标准化评估**使用一致的可能性和影响量表 +- **监管映射**到 NIST AI 600-1 类别和 ISO 42001 控制 +- **持续监控**通过定期审查周期 + +> **StrayMark 映射**：ETH 文档在变更级别评估个别风险。本目录按照 ISO 42001 附录 A.5 整合组织级风险。 + +--- + +## 2. 风险评估方法论 + +### 2.1 量表 + +| 评分 | 可能性 | 影响 | +|------|--------|------| +| 1 | 罕见 — 不太可能发生 | 可忽略 — 对运营影响极小 | +| 2 | 不太可能 — 可能在特殊情况下发生 | 轻微 — 有限影响，易于管理 | +| 3 | 可能 — 在某些时候可能发生 | 中等 — 明显影响，需要响应 | +| 4 | 很可能 — 在大多数情况下可能发生 | 重大 — 对运营或个人有重大影响 | +| 5 | 几乎确定 — 预计会经常发生 | 严重 — 关键影响，可能引发监管行动 | + +### 2.2 风险评分计算 + +**风险评分 = 可能性 x 影响** + +| 风险评分 | 风险级别 | 所需行动 | +|----------|----------|----------| +| 1–4 | Low | 接受或监控；在下一审查周期记录 | +| 5–9 | Medium | 实施额外控制措施；每季度审查 | +| 10–15 | High | 紧急实施控制措施；每月审查 | +| 16–25 | Critical | 需要立即行动；上报管理层 | + +### 2.3 风险管理阶段（ISO/IEC 23894） + +| 阶段 | 描述 | ISO 23894 参考 | StrayMark 证据 | +|------|------|----------------|---------------| +| 识别 | 发现和描述 AI 风险 | 第 6.1 条 | ETH 文档、本目录 | +| 评估 | 评估可能性、影响和风险评分 | 第 6.2 条 | 本目录中的风险评分 | +| 处置 | 选择和实施控制措施以缓解风险 | 第 6.3 条 | 当前控制措施列、ADR 记录决策 | +| 监控 | 跟踪残余风险和控制措施有效性 | 第 6.4 条 | 审查日期、`straymark metrics` | + +--- + +## 3. 风险登记表 + +### RISK-001 — 分类模型中的偏见 + +| 字段 | 值 | +|------|-----| +| **风险 ID** | RISK-001 | +| **类别** | 偏见（NIST：`bias`） | +| **描述** | 由于训练数据不平衡或特征选择存在偏见，分类模型对受保护的人口统计群体产生系统性不公平的结果。 | +| **可能性** | 4 | +| **影响** | 4 | +| **风险评分** | 16 (Critical) | +| **当前控制措施** | 训练期间评估公平性指标；ETH 文档中的偏见审计；测试套件中的人口统计均等性检查。 | +| **残余风险** | Medium — 控制措施减少但无法消除边界情况中的偏见。 | +| **负责人** | [AI 伦理审查员] | +| **审查日期** | [YYYY-MM-DD] | + +> **ISO 42001 映射**：A.5.2（风险评估）、A.6.2.3（训练和测试）、A.7.3（ML 数据质量） + +--- + +### RISK-002 — 训练数据泄露 + +| 字段 | 值 | +|------|-----| +| **风险 ID** | RISK-002 | +| **类别** | 隐私（NIST：`privacy`） | +| **描述** | 训练数据集中包含的个人身份信息（PII）或专有数据通过模型输出、记忆化或提取攻击被暴露。 | +| **可能性** | 3 | +| **影响** | 5 | +| **风险评分** | 15 (High) | +| **当前控制措施** | 数据脱敏管道；训练前 PII 检测扫描；训练数据的访问控制；DPIA 已完成。 | +| **残余风险** | Medium — 对大型模型的提取攻击仍是一个不断演变的威胁。 | +| **负责人** | [数据保护官] | +| **审查日期** | [YYYY-MM-DD] | + +> **ISO 42001 映射**：A.5.3（影响评估）、A.7.2（开发数据）、A.7.5（数据获取） + +--- + +### RISK-003 — 文本生成器中的幻觉 + +| 字段 | 值 | +|------|-----| +| **风险 ID** | RISK-003 | +| **类别** | 虚构（NIST：`confabulation`） | +| **描述** | 基于 LLM 的文本生成器产生看似合理但事实不正确的内容，在未经充分验证的情况下呈现给用户或下游系统。 | +| **可能性** | 4 | +| **影响** | 3 | +| **风险评分** | 12 (High) | +| **当前控制措施** | 生产环境中所有生成内容均需人工审查；已配置置信度阈值；使用带有来源引用的检索增强生成（RAG）。 | +| **残余风险** | Medium — 在专业领域中，幻觉仍可能通过人工审查。 | +| **负责人** | [开发团队负责人] | +| **审查日期** | [YYYY-MM-DD] | + +> **ISO 42001 映射**：A.6.2.4（验证和确认）、A.8.3（AI 输出信息）、A.9.5（人工监督） + +--- + +### RISK-004 — AI 供应链依赖 + +| 字段 | 值 | +|------|-----| +| **风险 ID** | RISK-004 | +| **类别** | 价值链（NIST：`value_chain`） | +| **描述** | 对第三方 AI 模型提供商（API、权重或基础设施）的关键依赖，带来服务中断、未通知的模型变更或继承漏洞的风险。 | +| **可能性** | 3 | +| **影响** | 4 | +| **风险评分** | 12 (High) | +| **当前控制措施** | 维护 AI 组件的 SBOM；供应商 SLA 监控；已配置备选提供商；模型版本锁定。 | +| **残余风险** | Medium — 供应商锁定限制了某些能力的备选方案。 | +| **负责人** | [AI 治理负责人] | +| **审查日期** | [YYYY-MM-DD] | + +> **ISO 42001 映射**：A.6.2.11（第三方组件）、A.10.2（AI 组件供应商）、A.10.3（共享 ML 模型） + +--- + +### [RISK-NNN] — [风险标题] + +| 字段 | 值 | +|------|-----| +| **风险 ID** | RISK-NNN | +| **类别** | [类别]（NIST：`[nist_category]`） | +| **描述** | [风险描述] | +| **可能性** | [1-5] | +| **影响** | [1-5] | +| **风险评分** | [计算值] | +| **当前控制措施** | [已实施的控制措施] | +| **残余风险** | [残余风险级别和说明] | +| **负责人** | [负责人] | +| **审查日期** | [YYYY-MM-DD] | + +--- + +## 4. NIST AI 600-1 风险类别 + +> 所有 12 个 NIST AI 600-1 风险类别的参考表。在上方登记表中分类风险时使用**类别 ID**。 + +| 类别 ID | 类别名称 | 描述 | +|---------|----------|------| +| `cbrn` | CBRN 信息 | 与 AI 使获取化学、生物、放射性或核武器信息成为可能相关的风险。 | +| `confabulation` | 虚构 | AI 生成看似合理但事实不正确或捏造信息的风险。 | +| `dangerous_content` | 危险内容 | AI 生成可能造成人身伤害或使危险活动成为可能的内容的风险。 | +| `privacy` | 数据隐私 | 通过数据收集、推断、记忆化或未经授权的披露对个人隐私造成的风险。 | +| `environmental` | 环境影响 | AI 训练和运行的环境成本风险，包括能源消耗和碳排放。 | +| `bias` | 有害偏见和同质化 | AI 输出和决策中系统性歧视或多样性减少的风险。 | +| `human_ai_config` | 人机配置 | 因人工监督程度不当或过度依赖 AI 系统输出而产生的风险。 | +| `information_integrity` | 信息完整性 | AI 生成的虚假信息或操纵对信息生态系统完整性造成的风险。 | +| `information_security` | 信息安全 | AI 系统通过对抗性攻击、提示词注入或模型盗窃被利用的风险。 | +| `intellectual_property` | 知识产权 | AI 系统在训练或输出中侵犯版权、专利或商业秘密相关的风险。 | +| `obscene_content` | 淫秽、侮辱性或滥用内容 | AI 生成色情、侮辱性或滥用内容的风险。 | +| `value_chain` | 价值链和组件集成 | AI 供应链中对第三方 AI 组件、模型或服务依赖所带来的风险。 | + +--- + +## 5. ISO 42001 附录 A.5 映射 + +> 本目录满足以下 ISO 42001 附录 A.5 要求。 + +| 控制 | 要求 | 本目录如何满足 | +|------|------|----------------| +| A.5.2 | AI 风险评估 | 使用标准化评分方法论的风险登记表 | +| A.5.3 | AI 系统对个人的影响评估 | 影响列捕获对个人和群体的影响 | +| A.5.4 | AI 系统影响评估的文档化和报告 | 每个风险条目记录评估结果和审查日期 | + +> **交叉引用**：个别 ETH 文档提供变更级别的风险评估。DPIA 文档处理数据保护影响。本目录提供组织级别的综合视图。 + +--- + +## 6. 审查计划 + +| 审查类型 | 频率 | 下次审查 | 负责人 | +|----------|------|----------|--------| +| 全面目录审查 | 每季度 | [YYYY-MM-DD] | [AI 治理负责人] | +| 高风险/关键风险审查 | 每月 | [YYYY-MM-DD] | [风险管理者] | +| 事故后风险更新 | 每次 INC 之后 | 按需 | [事故负责人] | +| 新系统入库 | 按 AI-LIFECYCLE-TRACKER | 按需 | [系统负责人] | + +--- + +*AI 风险目录模板 — StrayMark 框架* +*对标 NIST AI 600-1 和 ISO/IEC 42001:2023 附录 C* + + diff --git a/.straymark/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md b/.straymark/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md new file mode 100644 index 0000000..634775d --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md @@ -0,0 +1,237 @@ +# C4 模型图指南 + +> 本指南介绍如何在 StrayMark 文档中使用 C4 模型的 Mermaid 语法，特别是在 ADR（架构决策记录）文档中。 + +**语言**: [English](../../C4-DIAGRAM-GUIDE.md) | [Español](../es/C4-DIAGRAM-GUIDE.md) | 简体中文 + +--- + +## 什么是 C4 模型？ + +C4 模型（Context、Containers、Components、Code）是一组用于在不同缩放级别可视化软件架构的抽象。由 Simon Brown 创建，它为描述和传达架构提供了一致的词汇表。 + +每个级别深入上一级别： + +| 级别 | 展示内容 | 在 StrayMark 中的使用场景 | +|------|----------|--------------------------| +| **1. Context** | 系统 + 用户 + 外部系统 | 系统级决策的 ADR，高层需求的 REQ | +| **2. Container** | 应用、数据库、服务 | 服务架构的 ADR，部署决策 | +| **3. Component** | 容器内的内部模块 | 模块级决策的 ADR，重大重构的 AILOG | +| **4. Code** | 类、接口、函数 | 在 StrayMark 中很少需要 — 仅用于关键设计模式 | + +--- + +## 级别 1：系统上下文 + +展示谁使用系统以及系统与哪些外部系统交互。 + +```mermaid +C4Context + title System Context — E-Commerce Platform + + Person(customer, "Customer", "Browses products and places orders") + Person(admin, "Admin", "Manages products and orders") + + System(ecommerce, "E-Commerce Platform", "Allows customers to browse and purchase products") + + System_Ext(payment, "Payment Gateway", "Processes credit card payments") + System_Ext(email, "Email Service", "Sends transactional emails") + System_Ext(shipping, "Shipping Provider", "Handles order fulfillment") + + Rel(customer, ecommerce, "Browses, orders", "HTTPS") + Rel(admin, ecommerce, "Manages", "HTTPS") + Rel(ecommerce, payment, "Processes payments", "HTTPS/REST") + Rel(ecommerce, email, "Sends emails", "SMTP") + Rel(ecommerce, shipping, "Creates shipments", "HTTPS/REST") +``` + +### 关键元素 + +| 元素 | 语法 | 描述 | +|------|------|------| +| 人员 | `Person(id, "Name", "Description")` | 用户或角色 | +| 系统 | `System(id, "Name", "Description")` | 被记录的系统 | +| 外部系统 | `System_Ext(id, "Name", "Description")` | 外部依赖 | +| 关系 | `Rel(from, to, "Label", "Technology")` | 通信流 | + +--- + +## 级别 2：容器 + +深入系统内部，展示高层技术选择：应用、数据存储以及它们之间的通信方式。 + +```mermaid +C4Container + title Container Diagram — E-Commerce Platform + + Person(customer, "Customer", "Browses and purchases products") + + System_Boundary(ecommerce, "E-Commerce Platform") { + Container(webapp, "Web Application", "React, TypeScript", "Provides the shopping experience") + Container(api, "API Service", "Rust, Actix-web", "Handles business logic and data access") + Container(worker, "Background Worker", "Rust, Tokio", "Processes async tasks: emails, reports") + ContainerDb(db, "Database", "PostgreSQL", "Stores products, orders, users") + ContainerQueue(queue, "Message Queue", "RabbitMQ", "Async task distribution") + } + + System_Ext(payment, "Payment Gateway", "External payment processor") + + Rel(customer, webapp, "Uses", "HTTPS") + Rel(webapp, api, "Calls", "HTTPS/JSON") + Rel(api, db, "Reads/Writes", "SQL") + Rel(api, queue, "Publishes tasks", "AMQP") + Rel(worker, queue, "Consumes tasks", "AMQP") + Rel(api, payment, "Processes payments", "HTTPS/REST") +``` + +### 关键元素 + +| 元素 | 语法 | 描述 | +|------|------|------| +| 边界 | `System_Boundary(id, "Name") { ... }` | 对容器进行分组 | +| 容器 | `Container(id, "Name", "Tech", "Description")` | 应用或服务 | +| 数据库 | `ContainerDb(id, "Name", "Tech", "Description")` | 数据存储 | +| 队列 | `ContainerQueue(id, "Name", "Tech", "Description")` | 消息队列 | + +--- + +## 级别 3：组件 + +深入单个容器，展示其内部组件。 + +```mermaid +C4Component + title Component Diagram — API Service + + Container_Boundary(api, "API Service") { + Component(auth, "Auth Module", "Rust", "Handles authentication and authorization") + Component(catalog, "Catalog Module", "Rust", "Product search and management") + Component(orders, "Orders Module", "Rust", "Order processing and fulfillment") + Component(payments, "Payments Module", "Rust", "Payment integration and reconciliation") + } + + ContainerDb(db, "Database", "PostgreSQL") + System_Ext(payment, "Payment Gateway") + + Rel(auth, db, "Reads users", "SQL") + Rel(catalog, db, "Reads/Writes products", "SQL") + Rel(orders, db, "Reads/Writes orders", "SQL") + Rel(orders, payments, "Initiates payment") + Rel(payments, payment, "Processes", "HTTPS/REST") +``` + +### 关键元素 + +| 元素 | 语法 | 描述 | +|------|------|------| +| 边界 | `Container_Boundary(id, "Name") { ... }` | 在容器内对组件进行分组 | +| 组件 | `Component(id, "Name", "Tech", "Description")` | 内部模块或包 | + +--- + +## 级别 4：代码 + +展示类、接口及其关系。在 StrayMark 中**很少需要** — 仅用于需要记录的关键设计模式。 + +对于代码级别的图，使用标准 Mermaid 类图而非 C4： + +```mermaid +classDiagram + class OrderService { + +create_order(cart: Cart) Order + +cancel_order(id: OrderId) Result + -validate_stock(items: Vec~Item~) bool + } + class PaymentService { + +process_payment(order: Order) PaymentResult + +refund(payment_id: PaymentId) Result + } + class Order { + +id: OrderId + +status: OrderStatus + +items: Vec~OrderItem~ + +total: Decimal + } + + OrderService --> PaymentService : uses + OrderService --> Order : creates +``` + +--- + +## PlantUML 替代方案 + +对于偏好使用 PlantUML 的团队，可以使用 [C4-PlantUML](https://github.com/plantuml-stdlib/C4-PlantUML) 库获取等效语法。 + +### Context（PlantUML） + +```plantuml +@startuml +!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml + +Person(customer, "Customer", "Browses and purchases") +System(ecommerce, "E-Commerce Platform", "Shopping platform") +System_Ext(payment, "Payment Gateway", "Processes payments") + +Rel(customer, ecommerce, "Uses", "HTTPS") +Rel(ecommerce, payment, "Processes payments", "REST") +@enduml +``` + +### Container（PlantUML） + +```plantuml +@startuml +!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml + +Person(customer, "Customer") +System_Boundary(c1, "E-Commerce Platform") { + Container(webapp, "Web App", "React", "UI") + Container(api, "API", "Rust", "Business logic") + ContainerDb(db, "Database", "PostgreSQL", "Data store") +} + +Rel(customer, webapp, "Uses", "HTTPS") +Rel(webapp, api, "Calls", "JSON/HTTPS") +Rel(api, db, "Reads/Writes", "SQL") +@enduml +``` + +--- + +## 与 StrayMark 文档的集成 + +### 在 ADR 文档中 + +当决策涉及以下情况时，在 `## Architecture Diagram` 部分添加 C4 图： +- 引入或移除系统、服务或数据存储 +- 更改服务间通信模式 +- 修改系统边界或部署拓扑 + +### 在 REQ 文档中 + +使用级别 1（Context）图来说明： +- 谁与系统交互 +- 涉及哪些外部系统 +- 高层数据流 + +### 选择合适的级别 + +| 决策范围 | C4 级别 | 示例 | +|----------|---------|------| +| "我们将集成 Stripe 进行支付" | Context | 新的外部系统 | +| "我们将把单体架构拆分为微服务" | Container | 新的服务架构 | +| "我们将把认证模块提取为独立模块" | Component | 内部重构 | +| "我们将使用策略模式进行定价" | Code（类图） | 设计模式 | + +--- + +## 参考资料 + +- [C4 Model — Simon Brown](https://c4model.com/) +- [Mermaid C4 Diagrams](https://mermaid.js.org/syntax/c4.html) +- [C4-PlantUML](https://github.com/plantuml-stdlib/C4-PlantUML) + +--- + +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/00-governance/i18n/zh-CN/CAC-FILING-GUIDE.md b/.straymark/00-governance/i18n/zh-CN/CAC-FILING-GUIDE.md new file mode 100644 index 0000000..5fb4227 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/CAC-FILING-GUIDE.md @@ -0,0 +1,115 @@ +# CAC 算法备案指南 — StrayMark + +> 完成 CACFILE 文档与办理国家互联网信息办公室(CAC)双重备案流程的实务指南。 + +**Languages**: [English](../../CAC-FILING-GUIDE.md) | [Español](../es/CAC-FILING-GUIDE.md) | 简体中文 + +--- + +## 何时需要 CAC 备案 + +具有 **舆论属性** 或 **社会动员能力** 的服务,根据以下规定须备案: + +- 《互联网信息服务算法推荐管理规定》(2022-03-01 施行) +- 《互联网信息服务深度合成管理规定》(2023-01-10 施行) +- 《生成式人工智能服务管理暂行办法》(2023-08-15 施行) + +适用规则的指标: + +- 服务生成、合成或传播可被公众查看的内容。 +- 服务使用排序、推荐、搜索或内容选择影响用户观点。 +- 服务运营于新闻、社交媒体、音视频、直播或生成式 AI 领域。 +- 服务提供给中国大陆用户。 + +如以上任一适用,在 MCARD 上设置 `cac_filing_required: true` 并创建 CACFILE。验证规则 **CROSS-007** 强制执行此关联。 + +--- + +## 单一备案 vs 双重备案 + +并行的两条监管路径: + +| 路径 | 主管机关 | 内容 | 适用 | +|------|--------|------|------| +| **算法备案** | 国家网信办(在线提交后) | 算法机制披露、目标受众、安全责任报告 | 所有范围内算法 | +| **生成式 AI 大模型备案** | 省级网信办 → 国家网信办 | 两阶段技术测试 + 算法披露 | 具有舆论属性 / 社会动员能力的生成式 AI 服务 | + +生成式 AI 服务通常需 **双重备案**:先省级安全评估,后国家级算法备案。设置 `cac_filing_type: dual`。 + +--- + +## 必备文档与信息 + +CACFILE 模板捕获标准输入。最常请求的资料: + +| 资料 | CACFILE 中位置 | 备注 | +|------|--------------|------| +| 服务概述 | § 服务概述 | 名称、提供者、应用领域、目标受众 | +| 算法自评估报告 | § 自评估 | 内容合规、隐私、偏见、知识产权、未成年人保护的风险 + 缓解 | +| 内部算法管理制度 | § 内部算法管理制度 | 指定责任人、投诉处理、日志 | +| 算法安全责任报告 | § 算法安全责任报告 | 依《算法推荐管理规定》第24条 | +| 训练数据描述 | § 训练数据描述 | 来源、规模、合法性、过滤的敏感类别 | +| 关键词阻断列表 | § 关键词阻断策略 | 防止生成颠覆国家政权、煽动分裂、破坏国家统一等内容 | +| 测试题集 | § 测试题集 | 红队提示词 + 通过阈值 | +| 服务协议 + 投诉渠道 | (自由文本,链接自 § 内部算法管理制度) | 用户面向条款与 SLA | + +--- + +## 备案状态生命周期 + +| 状态 | 含义 | +|------|------| +| `pending` | CACFILE 已起草但未提交 | +| `provincial_submitted` | 已提交至省级网信办;待决定 | +| `provincial_approved` | 省级决定批准;可继续国家级提交(双重备案) | +| `national_submitted` | 已提交至国家网信办 | +| `national_approved` | 备案号已发放(`cac_filing_number` 已填写) | +| `rejected` | 备案被拒绝;在 *备案轨迹* 中记录原因 | +| `not_required` | 初步评估认定服务不在范围 | + +合规检查 **CAC-002** 标记 `pending` 超过 90 天的备案为部分通过。**CROSS-006** 要求状态为 `*_approved` 时 `cac_filing_number` 不为空。 + +--- + +## 备案号的公开披露 + +`cac_filing_number` 一旦发放,提供者须在终端用户界面展示。常见形式: +- 服务首页脚注:"**算法备案号: 网信算备XXXXXXXXXXXX**" +- 应用内的 *设置 / 关于* 页面 +- 服务条款 + +在 *备案轨迹* 部分最后一行记录披露界面。 + +--- + +## 自评估风险类别 + +CACFILE § 自评估必须涵盖至少: + +- **内容合规**:防止违法内容生成(颠覆、分裂、恐怖主义、淫秽、暴力、民族仇恨等)。 +- **个人信息保护**:与 PIPL 对齐(交叉链接到 PIPIA)。 +- **偏见 / 不合理差别待遇**:涵盖价格歧视、排序操纵、人口偏见。 +- **知识产权**:训练数据许可、输出与受版权保护作品的相似性。 +- **未成年人保护**:对 18 岁以下用户的特殊处理 — 内容过滤、时间限制、防沉迷。 + +对使用第三方基础模型的服务,自评估必须包括对上游提供者备案状态的评估。 + +--- + +## 与其他 StrayMark 文档的关联 + +完整的备案资料集通常引用: + +```yaml +# CACFILE-2026-04-25-001 frontmatter 中 +related: + - MCARD-2026-04-25-001 # 备案的模型 + - TC260RA-2026-04-25-001 # TC260 风险评估 + - PIPIA-2026-04-25-001 # 如处理个人信息 + - AILABEL-2026-04-25-001 # GB 45438 标识方案 + - SBOM-2026-04-25-001 # 训练数据清单(GB/T 45652 合规) +``` + +`straymark compliance --standard china-cac` 沿此关联进行验证。 + + diff --git a/.straymark/00-governance/i18n/zh-CN/CHARTER-CHAIN-EVOLUTION.md b/.straymark/00-governance/i18n/zh-CN/CHARTER-CHAIN-EVOLUTION.md new file mode 100644 index 0000000..27e1f6d --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/CHARTER-CHAIN-EVOLUTION.md @@ -0,0 +1,197 @@ +# Charter 链演化 — StrayMark + +> 两个互补的模式，用于保持多 Charter 模块的诚实性：在 Charter 被声明之前刷新 SpecKit 工件；以及当审计发现在 `status: closed` 之后到达时，对已关闭的 Charter 进行修订。 + +**语言**: [English](../../CHARTER-CHAIN-EVOLUTION.md) | [Español](../es/CHARTER-CHAIN-EVOLUTION.md) | 简体中文 + +--- + +## 状态 + +**v0 — 已在 N=1 领域验证**（`StrangeDaysTech/sentinel` CHARTER-18, 2026-05-15, Issue #156）。 + +两个模式都是作为框架规范指南记录在此的约定。CLI 提供只读和脚手架辅助工具（`straymark charter refresh-suggest`、`straymark charter amend`）；模式本身由操作员驱动。一旦第二个采用者验证，任一模式都可能演化 —— 在那之前，N=1 领域警告适用（原则 #12）。 + +--- + +## 本文档存在的原因 + +StrayMark 的 Charter 模式（`STRAYMARK.md` §15）假设单个 Charter 是有界的工作单元。对孤立的 Charter 而言这是有效的。对链中*第一个* Charter 也是有效的。但当一个模块在数月内累积许多用户故事 Charter 时，会浮现两种逐 Charter 模式无法解决的失败模式： + +1. **链级别的规范漂移** —— SpecKit 工件（`plan.md`、`data-model.md`、`contracts/*`、`quickstart.md`、`research.md`）是针对链开始时模块的框架版本和现实编写的。在 3+ Charter 之后，累积的学习成果（提取的可重用模式、发现的代码缺口、演化的框架约定、批准的操作员决策）已使规范偏离了实现。直接从 Charter-N 关闭进入 Charter-(N+1) 声明会导致系统性的执行中作用域扩张和涌现的 `R (new, not in Charter)` 条目。 +2. **周期级别的审计发现** —— 外部审计周期在关闭后运行（审计员在关闭仪式后异步执行）。Critical 或 High 发现可在 Charter 被标记为 `status: closed` 之后到达。框架的选项是：(a) 为补救开新 Charter（重 —— 为 ~5 个文件编辑做完整声明 + Tasks + 仪式），或 (b) 将发现留在 `review.md` 中并失去"与 Charter 原子化"的属性。 + +模式 1 解决 (1)。模式 2 解决 (2)。两者组合 —— *接受过*模式 1 的 Charter 更可能*避免*模式 2，因为刷新吸收了审计本应在关闭后浮现的执行前风险。它们是互补的，而非可替代的。 + +--- + +## 模式 1 —— 预声明 SpecKit 刷新 + +### 何时适用此模式 + +当 SpecKit 驱动的模块满足**全部**以下条件时采用此模式： + +- 模块有**3 个或更多已关闭的 Charter**（链长 ≥ 3）。 +- 最近 3 个已关闭 Charter 的 `charter_telemetry.agent_quality.r_n_plus_one_emergent_count` 滚动均值**大于 6**。 +- 自链最近的分支点以来，没有刷新 PR 落入 SpecKit 工件。 + +运行 `straymark charter refresh-suggest ` 对你的 `.telemetry.yaml` 历史评估启发式。CLI 读取所命名模块的最近关闭的 Charter 并打印建议；不会进行任何变更。 + +低于阈值时，仅逐 Charter 模式就足够 —— 过早采用刷新会增加一个 PR 的开销而没有回报。 + +### 形状 + +一个**专用的刷新 PR** 在 Charter-N 关闭和 Charter-(N+1) 声明之间落地。它只触及 SpecKit 工件的**非锁定部分**： + +- `specs//plan.md` —— 阶段计划、依赖说明、排序。 +- `specs//data-model.md` —— 实体、字段、约定。 +- `specs//contracts/*.md` —— 接口契约、请求/响应形状。 +- `specs//quickstart.md` —— 可运行场景。 +- `specs//research.md` —— 累积的知识（见下方的"分类学习表"）。 + +`research.md` 承载着关键工件：一个**分类学习表**，整合链所学到的内容。最小桶： + +| 桶 | 此处放什么 | +|---|---| +| 可重用模式 | 跨 Charter 涌现的、应向前继承的惯用法 / 实用程序 / 包装器（例如 `withRLS` 包装器、品牌缓存 LRU、去重表模式）。 | +| 代码缺口 | 链发现但未关闭的已识别但未修复的工作（例如未接线的表、桩实现、缺失的列）。每个缺口是一个带描述 + 拥有者 Charter（当前或未来）的 `Gn` 条目。 | +| 纪律模式 | 链批准的过程学习（例如跨家族审计对、batch-complete 纪律、每批次关闭节奏）。 | +| 经验校正 | 规范偏离实现的地方。`EC1...ECn` 条目：规范说 X，现实是 Y，选择的协调。 | + +可选的**操作员决策（Dn）**在预声明时被批准，包含：决策、考虑的备选方案、选择的路径、理由。后续 Charter 将 Dn 作为契约继承。 + +### 机制 + +1. **刷新 PR** 在下一个 Charter 声明之前。可选的 AIDEC 记录刷新决策 + 考虑的备选方案。PR 标题应明确作用域（例如 `spec(): US plan refresh — LOCKED-aware Phase 7+8 redesign`）。 +2. **分类学习表** 在 `research.md` 中，包含上述四个桶。每个条目有稳定的 id（Pn / Gn / DPn / ECn），以便后续 Charter 可按 id 引用。 +3. **操作员决策（Dn）** 如适用 —— 明确列出，带备选方案 + 选择的路径 + 理由。 +4. **下一个 Charter 的 `## Context` 部分** 按 id 引用每个模式、校正和决策。Charter 作用域基于刷新后的现实，而非链开始的规范。 + +### 遥测 + +在*下一个* Charter 的遥测中填充 `charter_telemetry.pre_declare_refresh:`（消费刷新的那个，而非刷新 PR 本身）： + +```yaml +pre_declare_refresh: + enabled: true + refresh_pr: "owner/repo#76" + refresh_aidec: "AIDEC-YYYY-MM-DD-NNN-speckit-refresh" + reusable_patterns_integrated: 7 + code_gaps_integrated: 4 + discipline_patterns_integrated: 3 + empirical_corrections_integrated: 15 + operator_decisions_ratified: 3 +``` + +若未发生刷新，则整个块省略 —— 不在场意味着"模式未使用"。 + +### 为何有效（经验性） + +Sentinel CHARTER-18 是 7-Charter 链中第一个无需执行中补救 Charter 即可干净关闭的 Charter。`estimation_drift_factor: 1.0`、`pre_work.items_discovered_during_planning: 0`、`overall_satisfaction: 5/5`。操作员的漂移原因陈述：*"来自 PR #76 的 SpecKit 刷新 ... 消除了在先前 Charter 中驱动漂移的大部分歧义。无需执行中补救 Charter —— research.md 中的 EC1..EC15 经验校正清单将本会是执行前风险的东西吸收为执行中觉察。"* + +--- + +## 模式 2 —— 关闭后审计驱动的修订（Batch N.4） + +### 何时适用此模式 + +当 Charter 被标记 `status: closed` 之后满足**全部**以下条件时采用此模式： + +- 在关闭后的 `review.md` 中浮现一个或多个被评定为 **Critical** 或 **High** 的外部审计发现。 +- Charter 的 `closure_criterion` 由于未补救的发现而实质上未满足（即按现状发布将使关闭无效）。 +- 修复表面适合**一个内聚的 PR**（~< 25 个文件，无架构重新打开 —— 无新抽象、无迁移、无 API 破坏）。 + +如果修复表面更大或属架构性，请改为开新 Charter。修订模式是为有界情形而存在的；它不是 Charter 规避机制。 + +### 形状 + +修订搭载在**与原 Charter 相同的 execute 分支**上（分支仍可合并到 `main`；修订提交落在其上）。一个**新 AILOG** 记录修订 —— 不是原 AILOG 的编辑。 + +``` +charter--execute 分支 +├── （原始提交 —— Charter execute 工作） +├── 提交 X：charter close（status: closed，写入 telemetry.yaml） +└── 提交 Y：charter-(batch-7.4): audit-driven remediation —— <简短摘要> + ↑ + AILOG-YYYY-MM-DD-MMM（新）记录此提交 + AILOG-YYYY-MM-DD-NNN（原）获得一个 `## Historical correction` 子节 + 向前指向 AILOG-...-MMM +``` + +### 机制 + +1. **相同的 execute 分支** —— 不要从 `main` 分叉。原 Charter 的 execute 分支仍是单元；修订提交搭载在其上。 +2. **新 AILOG** 在 `.straymark/07-ai-audit/agent-logs/` 下记录修订。约定：`risk_level: high` 且 `review_required: true`。新 AILOG 携带一个 `amends:` 字段指回原 AILOG id。 +3. **原 AILOG 中的历史校正** —— 在原 AILOG 末尾追加一个 `## Historical correction (YYYY-MM-DD)` 子节，含指向新 AILOG 的前向指针。审计决策与执行决策不同；原始的主体保持完整作为历史记录。 +4. **PR 评论** —— 如果 execute PR 尚未合并，将修订提交添加到其中并以"Batch N.4 amendment"子节更新 PR 描述，列出已关闭的发现。如果 PR 已合并，开一个后续 PR 引用原 PR 和 AILOG。 +5. **遥测** —— 填充 `charter_telemetry.post_close_amendment:`（见下）。使用 `straymark charter audit --merge-reports --merge-into ` 将外部审计发现合并到同一文件；CLI 在 v0.2+ 容忍 `external_audit: []` 占位符重写。 + +`straymark charter amend ` 为步骤 2、3 和 5 做脚手架（创建新 AILOG 桩，编辑原 AILOG 加上 Historical correction 子节，打印 YAML 块）。不触碰 git —— 操作员决定何时提交。 + +### 遥测 + +在 Charter 的 `.telemetry.yaml` 中填充 `charter_telemetry.post_close_amendment:`： + +```yaml +post_close_amendment: + applied: true + trigger: "external_audit" # external_audit | production_incident | deferred_implementation + ailog_id: "AILOG-YYYY-MM-DD-MMM" # 新 AILOG，而非原始的 + findings_closed: 5 + files_modified: 19 + effort_hours: 6.0 +``` + +若未发生修订，则整个块省略。 + +### 为何有效（经验性） + +Sentinel CHARTER-18 在 2026-05-15 关闭，带 `external-audit-pending.yaml`。审计报告于 2026-05-15..05-17 到达。五个发现（来自 `gpt-5.3-codex` 的 4 个 Critical/High、来自 `gemini-2.5-pro` 的 1 个 Critical、校准员发现的 1 个 Medium）是代码级修复 —— DI 接线、重试 header 解析、多租户过滤器、超时默认值。Batch 7.4 修订在一个内聚提交中关闭了所有五个（19 个文件，+2257/-106 行）。新 Charter 将为 ~6 小时的聚焦工程创建多周治理开销。 + +--- + +## 跨模式组合 + +两个模式在链的不同层级运作并组合： + +| 模式 | 层级 | 频率 | 吸收 | +|---|---|---|---| +| 预声明 SpecKit 刷新 | 链 / 模块 | 每 3+ Charter 一次 | 规范级漂移（架构假设、表命名、框架版本演化） | +| 关闭后审计驱动修订 | 周期 / Charter | 触发时按 Charter | 运行时级漂移（DI 接线、重试语义、多租户过滤器） | + +*接受过*模式 1 的 Charter 更可能*避免*模式 2 —— 刷新吸收了否则将作为关闭后发现浮现的执行前风险。但 CHARTER-18 *两者*都需要 —— 刷新处理规范级漂移；修订处理刷新无法触及的运行时级漂移。在链层级鼓励模式 1；在周期层级容忍模式 2。 + +--- + +## 用于上游新模式的权威 / 接受流程 + +本文档本身是 Sentinel 为这两个模式走过的接受流程的输出（Issue [#156](https://github.com/StrangeDaysTech/straymark/issues/156)）。上游新 Charter-链模式的标准流程是： + +1. **采用者本地 RFC** 位于采用者自己树中的 `.straymark/06-evolution/-rfc.md`。采用者先在那里发布模式 —— N=1 证据是必要的但不充分的。 +2. **上游 Issue** 在 `StrangeDaysTech/straymark` 镜像本地 RFC 主体，带遥测引用和 PR 链接。 +3. **上游接受** 以以下形式落地：(a) 此处 `00-governance/` 中描述模式规范的文档，(b) 遥测 schema 添加（opt-in），(c) 操作员面向机制的可选 CLI 脚手架。N=1 领域警告携带至 v1 稳定化。 +4. **第二领域验证** 在模式的 schema 字段从可选毕业到推荐之前。 + +`06-evolution/` 是飞行中 RFC 的标准采用者本地归宿。上游接受后，标准归宿是 `00-governance/.md` —— 此文档实例化的约定。 + +--- + +## 开放问题 + +- **阈值调优** —— `r_n_plus_one_emergent_count` 滚动均值 6 的阈值源于 Sentinel。第二个领域可能移动它。CLI `straymark charter refresh-suggest` 暴露 `--threshold N` 供采用者校准。 +- **模块启发式** —— `refresh-suggest ` 目前将 `` 与 Charter 标题和 slug 匹配。SpecKit 约定模块（`specs/-/`）可在未来的 fw 升级中通过 Charter 的 `originating_spec` 字段提供更严格的绑定。 +- **修订频率上限** —— 模式 2 受限于"一个内聚的 PR"。随时间接收两个或更多修订提交的 Charter 应被重新评估为原始关闭过早的信号。 + +--- + +## 相关 + +- [EMERGENT-OBSERVATION-DESIGN.md](EMERGENT-OBSERVATION-DESIGN.md) —— 元模式，Pattern 1 和 Pattern 2 都是其应用（形式化交叉引用 + 浮现的文化许可）。 +- [STRAYMARK.md §15](../../../STRAYMARK.md) —— Charter 生命周期及本文档扩展的逐 Charter 模式。 +- [SPECKIT-CHARTER-BRIDGE.md](SPECKIT-CHARTER-BRIDGE.md) —— SpecKit 工件如何映射到 Charter；模式 1 生活在此接缝上。 +- [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) —— 跨许多 AILOG 累积的 `§Follow-ups` 的姐妹模式。 +- [`.straymark/schemas/charter-telemetry.schema.v0.json`](../../schemas/charter-telemetry.schema.v0.json) —— `pre_declare_refresh` 和 `post_close_amendment` 在此定义。 + +--- + +*StrayMark fw-4.17.0 | [GitHub](https://github.com/StrangeDaysTech/straymark) | Issue [#156](https://github.com/StrangeDaysTech/straymark/issues/156)* diff --git a/.straymark/00-governance/i18n/zh-CN/CHINA-REGULATORY-FRAMEWORK.md b/.straymark/00-governance/i18n/zh-CN/CHINA-REGULATORY-FRAMEWORK.md new file mode 100644 index 0000000..81dcb04 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/CHINA-REGULATORY-FRAMEWORK.md @@ -0,0 +1,87 @@ +# 中国法规框架 — StrayMark + +> 在 `.straymark/config.yml` 中启用 `regional_scope: china` 时,StrayMark 涵盖的六项中国 AI / 数据法规的概览。 + +**Languages**: [English](../../CHINA-REGULATORY-FRAMEWORK.md) | [Español](../es/CHINA-REGULATORY-FRAMEWORK.md) | 简体中文 + +--- + +## 启用方式 + +中国法规检查为 **opt-in**。在 `.straymark/config.yml` 中启用: + +```yaml +regional_scope: + - global # NIST + ISO 42001(始终可用) + - eu # EU AI Act + GDPR + - china # 增加下表的 6 个框架 +``` + +启用 `china` 时: +- `straymark new` 暴露 4 种中国专属文档类型(PIPIA, CACFILE, TC260RA, AILABEL)。 +- `straymark compliance --all` 包含 6 个中国检查器。 +- `straymark validate` 强制执行 CROSS-004…CROSS-011 与 TYPE-003…TYPE-006。 + +不在 `regional_scope` 中包含 `china` 的项目不受影响。 + +--- + +## 覆盖矩阵 + +| # | 法规 | 类型 | 状态 | StrayMark 证据 | +|---|------|------|------|--------------| +| 1 | **TC260 人工智能安全治理框架 v2.0**(2025-09-15) | 推荐(待制定为 GB) | 生效 | TC260RA 模板;`tc260_risk_level`、`tc260_application_scenario`、`tc260_intelligence_level`、`tc260_application_scale` 字段 | +| 2 | **PIPL** + **PIPIA**(《个人信息保护法》第55-56条) | 强制 | 自 2021-11-01 起生效 | PIPIA 模板;`pipl_*` 字段;PIPIA 留存 ≥ 3 年 | +| 3 | **GB 45438-2025**《网络安全技术 人工智能生成合成内容标识方法》 | **强制** | 自 2025-09-01 起施行 | AILABEL 模板;MCARD 上的 `gb45438_*` 字段 | +| 4 | **CAC 算法备案**(《互联网信息服务算法推荐管理规定》;《生成式人工智能服务管理暂行办法》) | 范围内服务强制 | 生效 | CACFILE 模板;MCARD 上的 `cac_filing_required`、`cac_filing_number`、`cac_filing_status` 字段 | +| 5 | **GB/T 45652-2025** 预训练与微调数据安全 | 推荐 | 自 2025-11-01 起施行 | SBOM/MCARD 上的 `gb45652_training_data_compliance` 字段 | +| 6 | **CSL 2026** 网络安全法修订与《国家网络安全事件报告管理办法》 | 强制 | 自 2026-01-01 起生效 | INC 上的 "CSL 2026 Incident Reporting" 部分;`csl_severity_level`、`csl_report_deadline_hours` 字段 | + +--- + +## 文档类型 → 框架映射 + +| 框架 | 主模板 | 交叉引用 | 其他可选字段 | +|------|--------|--------|------------| +| TC260 v2.0 | TC260RA | ETH, MCARD | AILOG / SEC 上的 `tc260_risk_level` | +| PIPL / PIPIA | PIPIA | DPIA(交叉引用) | ETH / MCARD 上的 `pipl_applicable` | +| GB 45438 | AILABEL | MCARD(生成式模型) | MCARD 上的 `gb45438_applicable` | +| CAC 算法备案 | CACFILE | MCARD, SBOM | MCARD 上的 `cac_filing_number` | +| GB/T 45652 | SBOM/MCARD 中的章节 | TC260RA | `gb45652_training_data_compliance` | +| CSL 2026 | INC(扩展) | (无) | INC 上的 `csl_severity_level` | + +--- + +## 实施指南 + +| 框架 | 指南 | +|------|------| +| TC260 v2.0 风险分级 | [TC260-IMPLEMENTATION-GUIDE.md](TC260-IMPLEMENTATION-GUIDE.md) | +| PIPL 第55条触发 → PIPIA | [PIPL-PIPIA-GUIDE.md](PIPL-PIPIA-GUIDE.md) | +| 双重备案流程 | [CAC-FILING-GUIDE.md](CAC-FILING-GUIDE.md) | +| 显式 + 隐式标识 | [GB-45438-LABELING-GUIDE.md](GB-45438-LABELING-GUIDE.md) | + +--- + +## 合规检查 + +启用 `china` 范围后,通过 `straymark compliance --standard <名称>` 暴露以下检查: + +| `--standard` | 检查 ID | 验证内容 | +|--------------|--------|--------| +| `china-tc260` | TC260-001/002/003 | 至少存在一个 TC260RA;高风险等级要求人工审核;三个分级标准已填充 | +| `china-pipl` | PIPL-001/002/003/004 | 当 `pipl_applicable` 或敏感数据时存在 PIPIA;跨境传输已记录;留存 ≥ 3 年 | +| `china-gb45438` | GB45438-001/002/003 | MCARD 声明生成式内容时存在 AILABEL;声明显式 + 隐式标识策略;元数据字段已填充 | +| `china-cac` | CAC-001/002/003 | `cac_filing_required: true` 时存在 CACFILE;状态未滞留于 `pending` 超过 90 天;`*_approved` 时填写备案号 | +| `china-gb45652` | GB45652-001/002 | SBOM 声明每条训练数据合规;MCARD 描述数据安全控制 | +| `china-csl` | CSL-001/002/003 | INC 包含 `csl_severity_level`;时限与严重程度一致(1h ↔ particularly_serious、4h ↔ relatively_major);≥ relatively_major 提交 30 天事后审查 | + +`straymark compliance --region china` 一次性运行全部 6 项。 + +--- + +## 资料来源 + +详细参考英文版本及英文版底部的链接列表。 + + diff --git a/.straymark/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md b/.straymark/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md new file mode 100644 index 0000000..e779472 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md @@ -0,0 +1,313 @@ +# 文档策略 - StrayMark + +**语言**: [English](../../DOCUMENTATION-POLICY.md) | [Español](../es/DOCUMENTATION-POLICY.md) | 简体中文 + +## 本策略为何存在 + +StrayMark 将资深软件工程工作的认知纪律——明确的范围、声明的决策、命名的风险、记录的备选方案、可审计的轨迹——外化为与代码并存的版本化文件。本策略定义了使这种纪律可被审计的文档类型、元数据和治理规则。 + +作为产出这些文物的副作用，项目会积累与主流 AI 治理框架清晰映射的证据： + +- **ISO/IEC 42001:2023** — AI 管理系统的核心标准 +- **EU AI Act**（2026年8月生效）— 风险分类、透明度、事件报告 +- **NIST AI RMF 1.0 + AI 600-1** — AI 风险管理功能和生成式 AI 配置文件 +- **ISO/IEC 23894:2023** — AI 风险管理框架 +- **GDPR** — 数据保护和隐私影响评估 + +本策略首先是为工程工作而写；当工作以纪律方式被记录时，合规便是自然而然的副产品。完整标准参考请见第 8 节，产品层面的论据则见上游仓库的 `Propuesta/straymark-design-principles.md`。 + +--- + +## 1. 文件命名约定 + +### 标准格式 + +``` +[TYPE]-[YYYY-MM-DD]-[NNN]-[description].md +``` + +| 组成部分 | 说明 | 示例 | +|-----------|------|------| +| `TYPE` | 文档类型前缀 | `AILOG`, `AIDEC`, `ADR` | +| `YYYY-MM-DD` | 创建日期 | `2025-01-27` | +| `NNN` | 当天的序列号 | `001`, `002` | +| `description` | 简要描述（kebab-case 格式） | `implement-oauth` | + +### 示例 + +``` +AILOG-2025-01-27-001-implement-oauth.md +AIDEC-2025-01-27-001-testing-framework-selection.md +ADR-2025-01-27-001-microservices-architecture.md +REQ-2025-01-27-001-user-authentication.md +``` + +--- + +## 2. 必需的元数据（Frontmatter） + +所有文档必须在开头包含 YAML 元数据： + +```yaml +--- +id: AILOG-2025-01-27-001 +title: OAuth Authentication Implementation +status: draft | accepted | deprecated | superseded +created: 2025-01-27 +updated: 2025-01-27 +agent: claude-code-v1.0 +confidence: high | medium | low +review_required: true | false +risk_level: low | medium | high | critical +tags: + - auth + - security +related: + - ADR-2025-01-20-001 + - REQ-2025-01-15-003 +--- +``` + +### 必填字段 + +| 字段 | 说明 | +|------|------| +| `id` | 唯一标识符（与文件名相同，不含 .md） | +| `title` | 描述性标题 | +| `status` | 当前文档状态 | +| `created` | 创建日期 | +| `agent` | 创建文档的代理标识符 | +| `confidence` | 代理的置信度级别 | +| `review_required` | 是否需要人工审核 | +| `risk_level` | 变更风险级别 | + +### 可选字段 + +| 字段 | 说明 | 使用时机 | +|------|------|----------| +| `updated` | 最后更新日期 | 任何更新时 | +| `tags` | 分类标签（参见以下约定） | 始终建议使用 | +| `related` | 关联文档的引用（参见以下约定） | 存在交叉引用时 | +| `supersedes` | 本文档替代的文档 ID | 替代其他文档时 | +| `superseded_by` | 替代本文档的文档 ID | 由替代文档设置 | +| `eu_ai_act_risk` | EU AI Act 风险分类：`unacceptable \| high \| limited \| minimal \| not_applicable` | 当变更涉及 EU AI Act 管辖的 AI 系统时 | +| `nist_genai_risks` | NIST AI 600-1 风险类别：`[privacy, bias, confabulation, ...]` | 当变更涉及生成式 AI 组件时 | +| `iso_42001_clause` | ISO 42001 条款：`[4, 5, 6, 7, 8, 9, 10]` | 映射到 ISO 42001 控制措施时 | +| `lines_changed` | 变更行数（可自动计算） | 在 AILOG 文档中 | +| `files_modified` | 修改的文件列表（可自动计算） | 在 AILOG 文档中 | +| `observability_scope` | OTel 埋点级别：`none \| basic \| full` | 当变更涉及可观测性埋点时 | +| `api_spec_path` | OpenAPI/AsyncAPI 规范文件路径 | 在 REQ 文档中，当需求涉及 API 接口时 | +| `api_changes` | 受影响的 API 端点列表 | 在 ADR 文档中，当决策修改公共 API 时 | +| `reviewed_by` | 人工审批人的身份（邮箱、GitHub 用户或 DID） | 由审批人在正式批准 `review_required: true` 文档时填写 | +| `reviewed_at` | 正式批准日期（`YYYY-MM-DD`，必须 ≥ `created`） | 与 `reviewed_by` 一同设置 | +| `review_outcome` | 闭环信号：`approved \| revisions_requested \| rejected` | 与 `reviewed_by` 一同设置。其存在即为"人工已审"的规范信号——见下方 §3.5 | + +### 标签约定 + +标签是用于分类和搜索的**自由格式关键词**。它们有助于在项目中发现相关文档。 + +**格式规则：** +- 使用 **kebab-case**（小写，连字符分隔）：`gnome-integration`、`sqlite`、`api-design` +- 每个标签一个概念 — 避免复合标签，如 `auth-and-security` +- 建议范围：每个文档 **3 到 8 个标签** +- 标签应描述文档的**主题**、**技术**、**组件**或**关注点** + +**示例：** +```yaml +tags: [sqlite, persistence, hexagonal-architecture, repository-pattern] +``` + +### 关联文档约定 + +关联引用将文档链接到同一项目中的其他 **StrayMark 文档**。它们支持在 `straymark explore` 等工具中进行交叉导航。 + +**格式规则：** +- 使用**文档文件名**（含 `.md` 扩展名）：`AILOG-2026-02-03-001-implement-sync-item.md` +- 对于治理文档或非类型化文档，直接使用文件名：`AGENT-RULES.md`、`DOCUMENTATION-POLICY.md` +- 路径相对于 `.straymark/` 解析 — 如果文档在子目录中，请包含从 `.straymark/` 开始的路径：`07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implement-sync-item.md` +- 当文件与引用文档在同一目录时，文件名即可 +- **不要使用**外部任务 ID（`T001`、`US3`）、issue 编号或 URL — 这些属于文档正文，不属于 frontmatter +- **不要使用**不含描述的部分 ID（优先使用 `AILOG-2026-02-03-001-implement-sync-item.md` 而非 `AILOG-2026-02-03-001`） + +**示例：** +```yaml +# 同一目录或已知位置 — 文件名即可 +related: + - AIDEC-2026-02-02-001-sqlite-bundled-vs-system.md + - AGENT-RULES.md + +# 特定子目录中的文档 — 包含从 .straymark/ 开始的路径 +related: + - 07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-implement-sync-item.md + - 02-design/decisions/ADR-2026-01-15-001-use-hexagonal-architecture.md +``` + +**解析规则：** CLI 按以下顺序解析引用：(1) 精确 ID 匹配，(2) `.straymark/` 中任意位置的文件名匹配，(3) 路径后缀匹配。使用完整文件名可提供最可靠的解析。 + +--- + +## 3. 文档状态 + +``` +identified ──┐ + ├──► draft ──────► accepted ──────► deprecated + │ │ │ + │ │ ▼ + │ └──────► superseded + │ + └──► (TDE 专用入口状态，见 §6) + │ + ▼ + resolved + (TDE 专用终态——债务已偿；见 §6) +``` + +| 状态 | 说明 | +|------|------| +| `identified` | 由代理驱动发现的类型的入口状态（今日仅 TDE）。在生命周期校验上等同于 `draft`——期望人工审阅者来排定优先级并推进。语义上有所区分，以便 adopter 的分析能够区分"代理发现了此债务"与"人工正在起草一份有意识的文档"。 | +| `draft` | 草稿中，待审核 | +| `accepted` | 已批准且为当前有效版本 | +| `resolved` | **TDE 专用终态**：本文档所述的技术债务已被解决；文档作为审计历史保留在磁盘上。区别于 `accepted`（"我们接受这笔债务继续存在"）、`superseded`（"另一份 TDE 取代了它"）和 `deprecated`（"TDE 这一概念本身已不再适用"）。规范的关闭引用（偿清债务的 Charter、PR 或 commit）写入 `## 解决记录` 章节。 | +| `deprecated` | 已废弃，但保留作为参考 | +| `superseded` | 已被其他文档替代 | + +按类型的默认 status 映射位于 §6——大多数类型以 `draft` 或 `accepted` 进入，但 TDE 因代理自主权边界（代理识别、人工排序）以 `identified` 进入。TDE 是今日唯一拥有自定义终态（`resolved`）的类型；验证器全局接受 `resolved` 作为过渡安排。未来的按文档类型生命周期词汇表（issue #149 选项 B）将把 `resolved` 严格限定到 TDE；在此之前，将其用于非 TDE 文档可通过验证，但语义上不正确。 + +--- + +## 3.5 审批记录 + +`status` 记录文档的生命周期状态，`review_required: true` 记录*需要人工审核*。这两个字段都不记录人工审核*实际是否发生*。本节定义了需要正式审批的文档（AIDEC、ETH、MCARD、ADR、DPIA、INC、SEC 以及中国 scope 变体——触发条件见 AGENT-RULES.md §4）的规范闭环信号。 + +### 闭环信号 + +三个可选的 frontmatter 字段，由审批人在批准时填写： + +```yaml +reviewed_by: pepe@example.com # 邮箱 | github 用户 | DID +reviewed_at: 2026-05-02 +review_outcome: approved # approved | revisions_requested | rejected +``` + +语义： + +- **`review_outcome` 的存在即为闭环信号。** 一份 `review_required: true` 且无 `review_outcome` 的文档处于*待审核*状态。 +- 批准之后**不**将 `review_required: true` 改为 `false` —— 它作为"为何最初需要审核"的历史记录保留下来。 +- `reviewed_at` 必须 `>= created`。如果 `reviewed_by` 已设置，`reviewed_at` 与 `review_outcome` 也必须设置（由 `straymark validate` 校验）。 +- `review_outcome: revisions_requested` 支持迭代审核循环：文档被更新，审批人最终再次批准。约定是用最新一次的审批覆盖三个字段（frontmatter 仅保留最新状态）；下方 body 章节保留历史。 + +### Body 章节（规范的散文形式） + +添加在文档正文的末位（例如：AIDEC/ADR 的 `## References` 之前；DPIA 的 `## Review Schedule` 之后；INC 的 `## Post-Mortem Review` 之后）。对于已包含 `## Approval` 表格形式的模板（ETH、MCARD、SEC、PIPIA、CACFILE、TC260RA、AILABEL），任一形式都是规范的；frontmatter 字段才是机器可读的真相源。 + +```markdown +## Approval + +**Approved**: 2026-05-02 by `pepe@example.com`. + +<可选的审批人备注——观察、条件、批准范围。如果没有需要补充于 frontmatter +之外的内容，可整节省略。> +``` + +### 多审批人流程（前瞻性） + +对于需要多审批人的文档（如 ETH 同时需要法务和工程的 sign-off），v1 的规范是在 body 中按时间顺序追加多个 `## Approval` 块，frontmatter 反映*最新*一次的批准。结构化的 `review:` 数组形式（每个审批人一条）属于前瞻性，不在 v1 中——会等到至少一个真实采用项目以真实数据演练多审批人流程后再加入。 + +### CLI 工具 + +`straymark approve --outcome approved --reviewer [--notes "..."] [--at YYYY-MM-DD]` 一次性写入 frontmatter 字段与 body 章节。`straymark validate --check-pending-reviews [--max-pending-days N]` 列出 `review_required: true` 且早于 `N` 天但仍无 `review_outcome` 的文档（warn-only，不报错）。详见 CLI-REFERENCE.md。 + +--- + +## 4. 风险级别 + +| 级别 | 使用场景 | 是否需要审核 | +|------|----------|-------------| +| `low` | 外观修改、文档更新 | 否 | +| `medium` | 新功能、代码重构 | 建议审核 | +| `high` | 安全、敏感数据、公共 API | 是 | +| `critical` | 不可逆变更、生产环境 | 强制审核 | + +--- + +## 5. 置信度级别 + +| 级别 | 含义 | 操作 | +|------|------|------| +| `high` | 代理对决策确信无疑 | 继续执行 | +| `medium` | 代理有轻微疑虑 | 记录替代方案 | +| `low` | 代理需要验证 | 标记 `review_required: true` | + +--- + +## 6. 目录结构 + +``` +.straymark/ +├── 00-governance/ # 策略和规则 +├── 01-requirements/ # 系统需求 +├── 02-design/ # 设计和架构 +│ └── decisions/ # ADR +├── 03-implementation/ # 实施指南 +├── 04-testing/ # 测试策略 +├── 05-operations/ # 运维 +│ └── incidents/ # 事后分析 +├── 06-evolution/ # 系统演进 +│ └── technical-debt/ # 技术债务 +├── 07-ai-audit/ # AI 代理审计 +│ ├── agent-logs/ # AILOG +│ ├── decisions/ # AIDEC +│ └── ethical-reviews/ # ETH +├── 08-security/ # SEC — 安全评估 +├── 09-ai-models/ # MCARD — 模型/系统卡 +└── templates/ # 模板 +``` + +### 文档类型 + +| 类型 | 名称 | 目录 | 默认状态 | 需要审核 | +|------|------|------|----------|----------| +| `AILOG` | AI 操作日志 | `07-ai-audit/agent-logs/` | `accepted` | 否 | +| `AIDEC` | AI 决策 | `07-ai-audit/decisions/` | `accepted` | 否 | +| `ETH` | 伦理审查 | `07-ai-audit/ethical-reviews/` | `draft` | 是 | +| `ADR` | 架构决策记录 | `02-design/decisions/` | `draft` | 是 | +| `REQ` | 需求 | `01-requirements/` | `draft` | 是 | +| `TES` | 测试计划 | `04-testing/` | `draft` | 是 | +| `INC` | 事故事后分析 | `05-operations/incidents/` | `draft` | 是 | +| `TDE` | 技术债务 | `06-evolution/technical-debt/` | `identified`（在此进入；债务偿清时 `resolved` 为终态——仅 TDE） | 否 | +| `SEC` | 安全评估 | `08-security/` | `draft` | 是（始终） | +| `MCARD` | 模型/系统卡 | `09-ai-models/` | `draft` | 是（始终） | +| `SBOM` | 软件物料清单 | `07-ai-audit/` | `accepted` | 否 | +| `DPIA` | 数据保护影响评估 | `07-ai-audit/ethical-reviews/` | `draft` | 是（始终） | + +--- + +## 7. 交叉引用 + +使用 `[TYPE-ID]` 格式进行引用： + +```markdown +此决策基于 [REQ-2025-01-15-003] 中定义的需求。 +另请参阅 [ADR-2025-01-20-001] 了解架构背景。 +``` + +--- + +## 8. 参考标准 + +| 标准 | 版本 | 在 StrayMark 中的范围 | +|------|------|---------------------| +| ISO/IEC/IEEE 29148:2018 | 2018 | 需求工程 — TEMPLATE-REQ.md | +| ISO/IEC 25010:2023 | 2023 | 软件质量模型 — TEMPLATE-REQ.md, TEMPLATE-ADR.md | +| ISO/IEC/IEEE 29119-3:2021 | 2021 | 软件测试文档 — TEMPLATE-TES.md | +| ISO/IEC 42001:2023 | 2023 | AI 管理系统 — AI-GOVERNANCE-POLICY.md（核心标准） | +| EU AI Act | 2024（2026年8月生效） | AI 法规 — ETH, INC, AILOG 监管字段 | +| NIST AI RMF 1.0 | 2023 | AI 风险管理 — ETH, AILOG 风险类别 | +| NIST AI 600-1 | 2024 | 生成式 AI 配置文件 — ETH/AILOG 中的 12 个风险类别 | +| ISO/IEC 23894:2023 | 2023 | AI 风险管理 — AI-RISK-CATALOG | +| GDPR | 2016/679 | 数据保护 — ETH（数据隐私）, DPIA | +| OpenTelemetry | 当前 | 可观测性 — OBSERVABILITY-GUIDE，可选 | + +--- + +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/00-governance/i18n/zh-CN/EMERGENT-OBSERVATION-DESIGN.md b/.straymark/00-governance/i18n/zh-CN/EMERGENT-OBSERVATION-DESIGN.md new file mode 100644 index 0000000..75901b2 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/EMERGENT-OBSERVATION-DESIGN.md @@ -0,0 +1,175 @@ +# 涌现式观察设计 — StrayMark + +> 为什么阅读 StrayMark 文档的智能体会主动浮现未被询问的内容：使得跨源不一致可被检测的结构性与文化性属性，以及已经实例化此元模式的应用模式金字塔。 + +**语言**: [English](../../EMERGENT-OBSERVATION-DESIGN.md) | [Español](../es/EMERGENT-OBSERVATION-DESIGN.md) | 简体中文 + +--- + +## 状态 + +**v0 — 已在 N=1 领域验证**（`StrangeDaysTech/sentinel`，Issue [#150](https://github.com/StrangeDaysTech/straymark/issues/150) → Issue [#156](https://github.com/StrangeDaysTech/straymark/issues/156)，2026-04-21 至 2026-05-15）。 + +本文档命名了 StrayMark 框架的一个*设计属性*，该属性产生了一个可经验观察的涌现行为。该属性**并非新增** —— 自 `00-governance/` 被规范化以来一直存在 —— 但它从未被*命名*，这使其对框架演化不可见，因此存在被意外侵蚀的风险。在此命名它可在原则 #12 的第二领域验证约束下保护它。 + +--- + +## 本文档存在的原因 + +一个在 Sentinel 工作的智能体浮现了一个观察 —— **无显式触发器、无操作员请求、且无设计用于产生该输出的 CLI 命令** —— 即 `specs/002-commshub/plan.md` 在七个连续 Charter（CHARTER-07..17，约 1 个月）中累积了十二条未被反映的经验性学习，并且对着该陈旧的 spec 填充 CHARTER-18 在下一个审计周期中产生关键/高风险发现的概率约为 50%。该观察产生了上游周期，最终在 fw-4.16.0 中固化为 `CHARTER-CHAIN-EVOLUTION.md` Pattern 1。 + +该行为之所以可复现，是因为文档机构的两个属性*一致地共存*。两者单独都不足以达成。命名两者及其组合，使得框架未来的演化可以审慎地保留它们，而非依赖惯性。 + +桥接文档 `SPECKIT-CHARTER-BRIDGE.md` 和链演化文档 `CHARTER-CHAIN-EVOLUTION.md` 文档化了此元的*一个应用*。本文档命名元本身，并枚举其他已发布的应用。 + +--- + +## 两个设计属性 + +### 属性 1 — 结构性交叉引用（形式化链接） + +框架**不**将跨文档的链接委托给智能体的直觉或散文。每个文档类型都有*必需的* frontmatter 字段和*规范的*章节，这些字段和章节在文档自身的结构中声明了它指向哪些其他文档以及自身的哪些章节对特定类型的浮现开放。 + +智能体在常规阅读中遇到的具体实例： + +- **解析到其他 StrayMark 文档的 frontmatter 链接字段**： + - AILOG / AIDEC frontmatter 中的 `originating_charter:`（[`AGENT-RULES.md` §5](AGENT-RULES.md)、[`SPECKIT-CHARTER-BRIDGE.md` Charter↔AILOG 章节](SPECKIT-CHARTER-BRIDGE.md)） + - Charter frontmatter 中的 `originating_spec:`（[`SPECKIT-CHARTER-BRIDGE.md`](SPECKIT-CHARTER-BRIDGE.md) §Frontmatter linkage） + - Charter frontmatter 中的 `originating_ailogs:`（聚合反向） + - 修订 AILOG frontmatter 中的 `amends:`（[`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 2） + - TDE frontmatter 中的 `promoted_from_followup:`（[`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md)） + - `related:`、`supersedes:`、`superseded_by:`（[`DOCUMENTATION-POLICY.md`](DOCUMENTATION-POLICY.md)） +- **以可查询形式持有差异的模板内规范章节**： + - AILOG 中的 `§Risk: R (new, not in Charter)`（[`AGENT-RULES.md` §3](AGENT-RULES.md)） + - 每个 AILOG 的 `## Follow-ups`（[`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md)） + - 多批次 AILOG 的 `## Batch Ledger` + - 修订时附加到原始 AILOG 的 `## Historical correction (YYYY-MM-DD)`（[`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md)） +- **使链接成本低廉的稳定 ID 约定**： + - 日期受限文档的 `[TYPE]-[YYYY-MM-DD]-[NNN]-[description]` + - `CHARTER-NN-slug`（无时间戳，跨重命名稳定） + - `FU-NNN` 全局单调，从不重新编号 +- **声明层间规范关系的桥接文档**： + - `SPECKIT-CHARTER-BRIDGE.md`（Spec ↔ Charter ↔ AILOG） + - `CHARTER-CHAIN-EVOLUTION.md`（Charter ↔ Charter 链 ↔ Spec 刷新） +- **机械地跨源的 CLI 命令**： + - `straymark charter drift `（声明范围 ↔ commits） + - `straymark charter refresh-suggest `（遥测滚动均值 ↔ 刷新需求） + - `straymark validate`（frontmatter ↔ schema ↔ 链接完整性） + +**属性 1 的要点**：当智能体遇到两个源之间的差异时，该差异是*结构性可见的* —— 而不是埋藏在散文中。智能体无需发明连接；连接由框架声明。 + +### 属性 2 — 无门禁的文化许可 + +框架明确且反复地给予智能体超越被询问任务进行浮现的许可 —— 并将该许可与无需预批准即可*执行*浮现（创建 AILOG、提交 TDE、打开 AIDEC）的自主权配对。操作员保留优先级分配，而非创建。 + +智能体遇到的具体段落： + +- **`AGENT-RULES.md` §6 "Be Proactive"** —— *"Identify potential risks, Suggest improvements when evident, Alert about technical debt"*。 +- **`AGENT-RULES.md` §6 "Be Transparent"** —— *"Explain the reasoning behind decisions, Document considered alternatives, Admit uncertainty when it exists"*。 +- **`AGENT-RULES.md` §12 Audit Checkpoint** —— *"the agent proactively offers an external multi-model audit"* —— 将浮现的*行为*制度化为工作流的一部分。 +- **`PRINCIPLES.md` §2 "AI Agent Transparency"** —— *"Not hide relevant information"*。 +- **`AGENT-RULES.md` §3 "Create Freely" 自主性表** —— AILOG、AIDEC、TDE 创建无需预批准；智能体提交，操作员优先级分配。 +- **`FOLLOW-UPS-BACKLOG-PATTERN.md` 脚本自动追加** —— `check-followups-drift.sh --apply` 在无操作员干预的情况下将 FU-NNN 条目添加到中心注册表。 + +**属性 2 的要点**：智能体将*"我应该说点什么吗？"*外化为*"是否存在一个规范章节，这里属于那里？"*。如果是，浮现不是判断 —— 而是已文档化规则的执行。浮现的成本低，因为目的地已预构建。 + +### 为什么组合很重要 + +仅属性 1 —— 形式化链接而无文化许可 —— 将产生没有智能体敢主动查询的可查询语料。仅属性 2 —— 许可而无结构性交叉引用 —— 将产生操作员无法行动的模糊浮现（"我认为某处可能有问题"）。 + +组合起来，它们产生观察到的行为：智能体读取 AILOGs，计数与起源 spec 实质上分歧的 `R(new, not in Charter)` 条目，看到 spec 已经一个月未刷新，并且 —— 因为 `§6 Be Proactive` 告诉它要警告，且因为分歧在框架词汇中有名称 —— 在继续被询问的任务之前，向操作员浮现*那个具体的、结构性奠基的差异*。 + +这就是元模式。 + +--- + +## 经验案例：Sentinel spec-drift 检测 + +该案例在 Issue [#150](https://github.com/StrangeDaysTech/straymark/issues/150) 和 [#156](https://github.com/StrangeDaysTech/straymark/issues/156) 中详细描述，并在 [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) 中固化为 Pattern 1。压缩序列： + +1. Sentinel 在约 1 个月内通过 CHARTER-07..17 运行 `specs/002-commshub/plan.md`（committed 2026-04-21）。十二条经验性学习在 AILOG 链中的 `§Risk: R(new, not in Charter)` 章节和 `## Follow-ups` 中累积。模式传播（handler 形状、表重用约定、RLS helper 等）在执行期间固化。 +2. CHARTER-18 即将被声明。智能体 —— 未被指示这样做 —— 将 `plan.md` 与 AILOGs（其中 `§Risk` 条目命名了 spec 的差距）以及代码（如果跨 Charter 运行的话，`straymark charter drift` 本可检测到每 Charter 的差异）三角化。每个 Charter 中的 `originating_spec:` 链接、每个 AILOG 中的 `originating_charter:` 以及框架的 `§Risk: R` 约定使三角化机械化而非英雄式。 +3. 智能体浮现 *"如果我们读取陈旧的 plan 来填充 CHARTER-18，下一个审计周期的 H1/M1 发现将是 pre-close 原子地修复分歧 —— 由于陈旧前提继承导致 ≥1 关键/高发现的概率约为 50%"* —— 引用按 ID 的具体 AILOGs 和具体的代码引用。 +4. 操作员将 Issue #150 作为 RFC 提交。Sentinel 本地 AIDEC 记录了所提议的范围受限刷新规范 + 三个机械化门。 +5. Issue #156 将该模式上游化。`CHARTER-CHAIN-EVOLUTION.md` Pattern 1 在 fw-4.16.0 中落地，包含遥测槽 `pre_declare_refresh:`、helper `straymark charter refresh-suggest` 和分类学习表合约。 + +该观察可经验复现：任何产生 ≥3 个间隔 ≥1 周的 Charter 的 spec 都会表现出某种程度的 plan-vs-code 漂移，并且阅读框架文档的智能体具有检测和浮现它的结构性和文化性许可。 + +--- + +## 实例金字塔 —— 元模式的应用 + +元模式位于若干已经规范化的模式之上。每个都是同一底层组合（形式化链接 + 文化许可）应用于特定源对的*应用*。 + +| 应用 | 源对 | 规范化位置 | +|---|---|---| +| 预声明 SpecKit 刷新（Pattern 1） | spec ↔ AILOGs ↔ 代码 | [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 1 | +| 关闭后审计驱动的修订（Pattern 2） | 审计发现 ↔ 已关闭 Charter | [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) Pattern 2 | +| Charter 漂移检测 | 声明范围 ↔ commits | [`SPECKIT-CHARTER-BRIDGE.md`](SPECKIT-CHARTER-BRIDGE.md) + `straymark charter drift` | +| Follow-ups backlog 漂移 | 每 AILOG `§Follow-ups` ↔ 中心注册表 | [`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md) + `check-followups-drift.sh` | +| TDE 与 `R` 升级 | 累积的 `§Risk: R` ↔ TDE backlog | [`AGENT-RULES.md`](AGENT-RULES.md) §3 | +| 外部审计 checkpoint | implementation-complete 状态 ↔ 多模型审查 | [`AGENT-RULES.md`](AGENT-RULES.md) §12 | + +这些不是临时约定。它们共享相同的形状：*通过 frontmatter 或章节链接连接的两个规范源，智能体被允许（有时被要求）浮现差异*。下一个应用轴 —— 无论它最终是什么 —— 都会在此表中认出自己。 + +--- + +## 反模式：元如何被破坏 + +元模式是脆弱的。以下每一项如果被引入，都会回退框架产生涌现观察的能力。 + +- **Frontmatter 链接作为可选**。如果新文档类型以 `related:` / `originating_*` 作为建议性而非必需性发布，则交叉引用图会出现盲点，智能体丢失通过该类型三角化的能力。 +- **规范章节被收拢为散文**。如果 `§Risk: R` 被替换为*"风险讨论"*，可查询性就蒸发了。智能体无法再计数 `R` 条目以检测驱动 `refresh-suggest` 的饱和阈值。自由散文不可查询；结构化章节可以。 +- **对智能体创建文档的门禁**。要求对填写 AILOG / AIDEC / TDE 进行预批准会扼杀属性 2。智能体回退到仅浮现被询问的内容，因为浮现成本超过了本地收益。 +- **没有涌现信号的遥测**。如果 `.telemetry.yaml` schema 演化但没有保留像 `r_n_plus_one_emergent_count` 这样的信号，操作员就失去了对智能体浮现涌现风险的频率的可见性。反馈循环断裂；元对框架演化变得不可见。 +- **绕过表面的 CLI 命令**。直接发出决策（不写 AILOG，不填充 `R` 章节）的 CLI 绕过了结构化表面。智能体下游的三角化退化，因为源对不再通过文档连接。 + +--- + +## 开放的应用轴 —— 元可在何处复制 + +本文档底层的审计识别出四个位置，其中结构性基础设施*部分*存在但文化许可或应用模式尚未命名。这些是元的未来应用候选，而非交付承诺。 + +- **MCARD ↔ 部署的模型代码** —— `TEMPLATE-MCARD.md` 存在；Charter 遥测中没有 `model-version-at-close` 字段，没有 AILOG `deployed_mcard:` 链接字段，没有漂移检测模式。与归档 MCARD 分歧的模型部署目前不可见。 +- **SBOM ↔ lockfiles** —— `AI-RISK-CATALOG.md` §RISK-004 提到 AI 组件的 SBOM 维护；没有链接到 SBOM 的规范 AILOG 字段，没有漂移脚本（类似于 `check-followups-drift.sh`）比较声明的 SBOM 与实际的 `package.lock` / `requirements.txt`，没有依赖变化事件的遥测信号。 +- **生效中的 ADR ↔ 矛盾的实现** —— `.telemetry.yaml` schema 捕获 `decisions_contradicting_prior_adrs`，但没有协议告诉智能体在实现期间观察到矛盾时*何时*浮现。信号存在；浮现约定不存在。 +- **Constitution Check ↔ 框架版本升级** —— `SPECKIT-CHARTER-BRIDGE.md §Constitution Check re-evaluation cadence` 口头规范化了节奏；在 `straymark update-framework` 上不会触发自动警报。Charter 之间的框架升级可以静默地更改 Constitution 的门。 + +这四项在单个上游 RFC issue 中跟踪（在本文档落地之后提交）。每个都需要经验性 N=1 采用者验证后才能固化为命名模式 —— 适用原则 #12。 + +--- + +## 命名新元应用的权限/接受流程 + +`CHARTER-CHAIN-EVOLUTION.md` 记录的相同上游接受流程递归地适用于此元。新应用轴（上述四个之一，或浮现的第五个）通过以下方式落地： + +1. **采用者本地 RFC** 在 `.straymark/06-evolution/-rfc.md`，描述已存在（或正在添加）的结构连接以及智能体应遵循的文化许可规则。 +2. **上游 Issue** 镜像 RFC，引用经验观察发生的 AILOGs/Charters/遥测。 +3. **上游接受** 表现为：（a）更新相关模板/schema/治理文档以添加缺失的结构件（frontmatter 字段、规范章节、遥测信号）；（b）将该轴添加到本文档中的"实例金字塔"表；（c）可选的机械检测 CLI 脚手架。 +4. **第二领域验证** 在该轴的 schema 添加从可选升级为推荐之前。 + +本文档本身为元实例化了步骤 3.b —— 认识到现有应用共享单个底层属性的上游接受输出。 + +--- + +## 开放问题 + +- **"实质性分歧"的运营化**。原则 #8 措辞（[`PRINCIPLES.md`](PRINCIPLES.md)）将"实质性"留给智能体判断。每应用阈值（Pattern 1 使用 `r_n_plus_one_emergent_count > 6` 滚动平均）经验性地校准。是否可以达到跨轴阈值，或者每个轴是否必须校准自己的，仍然开放。 +- **遥测合并**。每个应用当前发出自己的遥测槽（`pre_declare_refresh:`、`post_close_amendment:`、`r_n_plus_one_emergent_count`）。合并的*"本 Charter 浮现的涌现观察"*计数器可能使元在度量级别可见。已推迟 —— 过早聚合可能丢失每轴信号粒度。 +- **采用者引导**。首次阅读 `STRAYMARK.md` 的新采用者应在足够早的时刻遇到元，以便他们在体验该模式时识别它。它是否驻留在 `QUICK-REFERENCE.md`、`STRAYMARK.md` 本身或新的引导章节中，仍然开放。 + +--- + +## 相关 + +- [`PRINCIPLES.md`](PRINCIPLES.md) §8 —— *跨源不一致浮现*（凝聚的文化规则）。 +- [`AGENT-RULES.md`](AGENT-RULES.md) §6 —— *Be Proactive*（运营授权）；§3 —— *TDE 与 `R`*（一个应用表面）；§12 —— *审计 Checkpoint*（制度化浮现）。 +- [`CHARTER-CHAIN-EVOLUTION.md`](CHARTER-CHAIN-EVOLUTION.md) —— Pattern 1, Pattern 2（两个最高级应用）。 +- [`SPECKIT-CHARTER-BRIDGE.md`](SPECKIT-CHARTER-BRIDGE.md) —— Charter 作为属性 1 链接最密集的桥接层。 +- [`FOLLOW-UPS-BACKLOG-PATTERN.md`](FOLLOW-UPS-BACKLOG-PATTERN.md) —— 每 AILOG ↔ 注册表表面的漂移检测。 +- [`DOCUMENTATION-POLICY.md`](DOCUMENTATION-POLICY.md) —— frontmatter 和 `related:` 字段规范。 +- [`../../STRAYMARK.md`](../../STRAYMARK.md) §15 —— 应用汇聚的有界单元 Charter。 + +--- + +*StrayMark fw-4.17.0 | [GitHub](https://github.com/StrangeDaysTech/straymark) | Issue [#150](https://github.com/StrangeDaysTech/straymark/issues/150) · [#156](https://github.com/StrangeDaysTech/straymark/issues/156)* diff --git a/.straymark/00-governance/i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md b/.straymark/00-governance/i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md new file mode 100644 index 0000000..4798806 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md @@ -0,0 +1,244 @@ +# Follow-ups Backlog 模式 - StrayMark + +> 用于跨多个 AILOG 和 Charter 管理累积的 `§Follow-ups` 与 `R (new, not in Charter)` 条目的可复制约定。 + +**语言**: [English](../../FOLLOW-UPS-BACKLOG-PATTERN.md) | [Español](../es/FOLLOW-UPS-BACKLOG-PATTERN.md) | 简体中文 + +--- + +## 状态 + +**v0 — 在 N=1 域中已验证**（`StrangeDaysTech/sentinel` CHARTER-12,2026-05-06）。 + +这是一个**约定**,不是 CLI 功能。Adopter 使用 markdown + 一个可移植的 bash 脚本在本地复制此模式。在第二个 adopter 验证后,该模式可能演变为 `straymark followups` 子命令(参见[未决问题](#未决问题))。 + +--- + +## 何时适用此模式 + +StrayMark 的 per-AILOG `§Follow-ups` 约定在写入时有效 — 创建 AILOG 时,实施者记录推迟到后续 Charter 或操作触发器的内容。在累积列表超出操作员可凭记忆扫描范围之前,这种方式都能正常工作。 + +当满足**任一**以下条件时,采用此模式: + +- 项目已累积 **约 20 个或更多 AILOG**,带有非平凡的 `§Follow-ups` 部分。 +- 操作员反复要求代理"列出项目中所有待处理事项",答案需要多文件扫描。 +- 一个"当 X 到来时执行"的 follow-up 几乎丢失,因为在 X 到来后从未重读过原始 AILOG。 +- Charter 回顾揭示出本应在数周前被分类为 `closed`、但从未被索引的 follow-ups。 + +低于此规模时,仅 per-AILOG 约定就足够了 — 过早采用此模式只会增加维护开销而无回报。 + +--- + +## 形式 + +### 注册表文件 + +规范路径下的单个 markdown 文件: + +``` +.straymark/follow-ups-backlog.md +``` + +### Frontmatter (YAML) + +```yaml +--- +last_scan: 2026-05-06 +last_scan_range: AILOG-NNNN-NN-NN-NNN..AILOG-NNNN-NN-NN-NNN # 可选 —— 涵盖的首个..末尾 AILOG +schema_version: v0 +total_open: 0 # 当前为 `open` 状态的条目计数 +total_promoted: 0 # 当前为 `promoted` 状态的条目计数(schema v0.1 新增 —— 见"提升为 TDE") +total_closed_in_session: 0 # 上次会话以来 `closed` 条目计数(可选,operator-maintained) +total_phase_blocked: 0 # `phase-blocked` 条目计数(可选) +buckets: + - ready + - time-triggered + - charter-triggered + - phase-blocked + - operational +fully_extracted_ailogs: + - AILOG-2026-04-11-001 + - AILOG-2026-04-12-001 + # ... 每个 follow-ups 已被处理的 AILOG 一个条目 +--- +``` + +`total_*` 计数器是**operator-maintained 的元数据**。drift 脚本不会自动更新它们 —— 它们位于 header 之中,使会话开始时的扫视就能看到注册表的脉搏,无需在 bucket 中翻页。`total_promoted` 在 schema v0.1 中固化(Sentinel adopter 的经验信号,fw-4.13.1),与现有的 `total_open` / `total_closed_in_session` / `total_phase_blocked` 模式保持一致。 + +`fully_extracted_ailogs` 列表是 drift 检测的**承重元数据**。所有 `§Follow-ups` 和 `R` 条目已被转移到注册表(或被显式分类为 superseded)的 AILOG 都属于此列表。Drift 检测将此列表与 repo 中具有 follow-up 内容的 AILOG 进行比对。 + +### Buckets + +五个 bucket 按触发类型组织条目: + +- `ready` — 现在可执行,无外部触发器依赖。 +- `time-triggered` — 基于日历的触发器(审计周期、周期性审查)。 +- `charter-triggered` — 由触及相关领域的未来 Charter 阻塞。 +- `phase-blocked` — 由尚不存在的未来组件或阶段阻塞。 +- `operational` — 操作员手动决策或外部系统操作。 + +### 条目 schema + +bucket 内的每个条目遵循以下形式: + +```markdown +### FU-NNN — <简短描述> +- **Origin**: AILOG-NNNN-NN-NN-NNN <指向源部分的指针> +- **Status**: open | in-progress | closed | superseded | promoted +- **Trigger**: ready | <日历日期> | when | <其他> +- **Destination**: +- **Cost**: <工作量估计> +- **Notes**: <自由格式上下文> +- **Promoted to**: +``` + +`FU-NNN` 在注册表整个生命周期内单调递增;条目关闭时不重新编号。 + +### Status 词汇表 + +- `open` — 待处理,尚未采取行动。 +- `in-progress` — 已声明或正在执行的 Charter 处理此条目。 +- `closed` — 条目已解决(Charter 已合并、操作任务已完成、时间已过且已审查)。 +- `superseded` — 由其他工作处理,该工作未直接引用此条目。 +- `promoted` — 条目因满足横向债务标准而被提升为 TDE 文档(见下方"提升为 TDE")。`Promoted to:` 字段携带 TDE id。 + +closed、superseded 和 promoted 条目保留在文件中(可审计的历史)。操作员可以将它们移到底部的 `## Bucket: closed` 部分以进行视觉整理,但绝不删除。 + +--- + +## 提升为 TDE + +某些 FU 条目不仅仅是延期任务 —— 它们描述的是值得拥有自己治理文档的**横向技术债务**(TDE)。提升标准与 `AGENT-RULES.md §3` 中的 TDE-vs-`R` 判定一致: + +- 该条目是*先前 Charter 的遗留*(已经历 ≥1 次 Charter 关闭仍未修复)。 +- 该条目*横跨多个模块或多个 Charter* —— 中央注册表已将其碎片化为共享同一根本原因的多个 bullet。 +- 该条目*需要在当前 scope 包络之外的专用 Charter* 来修复。 +- 该条目*需要人工决定优先级或分配*,操作员的周期性审查无法仅从 bullet 决定(impact × effort 矩阵、所有权)。 + +当上述任一条件成立时,将该 FU 条目提升为 `.straymark/06-evolution/technical-debt/` 下的 TDE 文档: + +1. 通过 `/straymark-new tde`(或 `straymark new --type tde`)创建 TDE。从 FU 条目的上下文填入 `impact`、`effort`、`type` 与正文各节。 +2. 在 TDE 的 frontmatter 中添加 `promoted_from_followup: FU-NNN` 以便溯源。 +3. 在 FU 条目中,设置 `Status: promoted`、`Destination: TDE-YYYY-MM-DD-NNN`,并添加 `Promoted to: TDE-YYYY-MM-DD-NNN`。如果你维护 `## Bucket: closed` 节,则将条目移过去;否则保持原位并更新状态。 + +FU 条目在提升后**不会被删除** —— 它在注册表中的存在就是显示 TDE 来源的审计轨迹。 + +### 两种提升形态 —— 提升已存在的 vs 创建时即追溯提升 + +上述工作流涵盖**标准情况**:`open` 状态的 FU 条目已存在于注册表中,并在周期性审查期间被提升为 TDE。还有一种同样有效的情况,源自 Sentinel CHARTER-13 回顾的经验: + +- **提升已存在条目** —— FU 数周或数个 Charter 之前已被(通常通过 `--apply`)登记为 `open`,经历过 ≥1 次 Charter 关闭仍未解决,并满足上述四项标准。标准流程。 +- **创建时即追溯提升** —— 在回顾(Charter 关闭仪式、审计周期、RFC 撰写)*期间* 该债务被识别为值得作为 TDE,且从未作为 `open` FU 存在。先创建 TDE;在注册表中以 *`Status: promoted`* 状态新增一个 FU 条目,提供从 TDE 回溯到原始上下文(AILOG 中的某个 `R`、calibrator 的 finding、被延期的分类)的审计轨迹。 + +两种形态在注册表中产生相同的终态:一个 `Status: promoted` 且具有 `Promoted to: TDE-YYYY-MM-DD-NNN` 指针的条目。区别在于条目是预先以 `open` 存在,还是天生即为 `promoted`。drift 脚本一视同仁(不按出生状态区分);统计 `total_promoted` 的 adopter 分析在两种情况下得到相同数字。 + +存疑时,优先创建 FU 条目 —— 即便是追溯创建 —— 因为它会把 TDE 交叉引用回触发该识别的 AILOG / R-号 / 源上下文。一个 `promoted_from_followup: FU-NNN` 指向 backlog 中实际存在的条目的 TDE,比指向一个虚构的 FU 更易导航。 + +### 何时提升 + +- **周期性审查** —— 当操作员做人工重新分类时,提升任何已经历 ≥2 次 Charter 关闭仍未解决且符合上述标准的条目。 +- **Charter 关闭** —— 在审查刚关闭的 Charter 所解决的条目时,如果发现*未*被解决且符合上述标准的条目,则提升它们,而不是保留为 `open`。 +- **Charter 声明前** —— 如果你即将声明一个 Charter,并注意到注册表中包含此 Charter 仅会*部分*处理的条目,那么未处理的部分可能应作为 TDE,而不是作为另一个被延期的 FU。 + +Drift 脚本(`scripts/check-followups-drift.sh`)在 v0 **不扩展**支持提升候选 —— 提升由操作员驱动。未来 v1 增强可标记符合"经历 ≥2 个 Charter"启发式的条目,但这等到第二个 adopter 验证模式后才会固化(与 v0 → v1 其余部分相同的门槛)。 + +--- + +## Drift 检测 + +一个小的 bash 脚本是验证层,使注册表与新 AILOG 保持同步。该脚本位于 adopter 的 repo 中(建议路径:`scripts/check-followups-drift.sh`),有三种模式。 + +### 模式 + +- **默认** — 扫描 `git diff origin/main..HEAD`(回退到 `HEAD~1..HEAD`)中修改的 AILOG。对任何具有 `§Follow-ups` / `R (new)` 内容但不在 `fully_extracted_ailogs` 中的 AILOG 发出警告。drift 时退出 1。 +- **`--apply`** — 相同的扫描,但自动在 `## Bucket: ready` 下追加新条目,使用自动生成的 `FU-NNN` id,并将 AILOG id 追加到 `fully_extracted_ailogs`。操作员稍后将其重新分类到正确的 bucket。 +- **`--scan-all`** — 扫描项目中的每个 AILOG(周期性完整扫描)。 + +### Per-AILOG 与 per-bullet 粒度 + +跟踪是 **per-AILOG**,而非 per-bullet。AILOG 要么被完全提取(其 id 在 `fully_extracted_ailogs` 中 — 信任注册表),要么未被提取(提取所有内容)。Per-bullet 匹配将需要指纹识别(文本哈希或模糊比较),每当注册表条目对 AILOG 的 bullet 进行改写时,这都会产生误报 — 而经过整理的条目总是会改写。 + +Per-AILOG 粒度的成本:当在 Charter 关闭后向已提取的 AILOG 添加 follow-up 时,drift 检测无法发现。修复由操作员驱动 — 手动从 `fully_extracted_ailogs` 中移除该 AILOG 并使用 `--apply` 重新运行。这种权衡对 v0 是有意为之,因为大多数 AILOG 在 Charter 关闭后是 write-once。 + +### 脚本模板 + +参考实现(约 290 行 POSIX bash)位于 `StrangeDaysTech/sentinel` 的 `scripts/check-followups-drift.sh`。将其复制到你的 repo 并调整顶部常量: + +```bash +BACKLOG_FILE=".straymark/follow-ups-backlog.md" +AILOG_DIR=".straymark/07-ai-audit/agent-logs" +``` + +脚本仅使用 `awk` 和 `grep` — 没有 jq、yq 或重型依赖。在 Linux 和 macOS 之间可移植。 + +--- + +## 代理集成 + +代理(Claude / Gemini 等)成为注册表的主要维护者。添加到你的 `CLAUDE.md` / `AGENT.md`: + +```markdown +## Follow-ups backlog + +- **会话开始**: 浏览 `.straymark/follow-ups-backlog.md` 以了解项目中所有待处理事项。 +- **Pre-commit 检查**: 创建或修改了任何带有 `## Follow-ups` 或 `R (new, not in Charter)` 条目的 AILOG 吗? → 在同一个 commit 中运行 `scripts/check-followups-drift.sh --apply` 以扩展 backlog。 +- **Charter 关闭后**: 审查 Charter 解决的条目;将其标记为 `closed`(在 `Notes` 中带有关闭 Charter id)或 `superseded`。对于未解决但符合 TDE 标准的条目(先前 Charter 的遗留、横向、需要专用 Charter、需要人工优先级),将其提升为 TDE 文档(见本模式的"提升为 TDE"以及 `AGENT-RULES.md §3`)。 +``` + +这使代理成为维护者,脚本成为验证层,操作员成为周期性审查者(重新分类、标记 closed、修剪 superseded、在符合标准时提升为 TDE)。 + +--- + +## 采用流程 + +对于从零开始的 adopter: + +1. 创建 `.straymark/follow-ups-backlog.md`,使用上述 frontmatter(初始 `fully_extracted_ailogs:` 列表为空)和五个 `## Bucket: ` 标题。 +2. 将参考脚本从 `StrangeDaysTech/sentinel` 复制到 `scripts/check-followups-drift.sh`。如果你的 AILOG 位于其他位置,调整 `AILOG_DIR`。 +3. 运行 `scripts/check-followups-drift.sh --scan-all --apply` 从现有 AILOG 播种注册表。 +4. 手动将自动生成的 `## Bucket: ready` 条目重新分类到正确的 bucket。这是一次性 triage,对于约 50 个条目的 backlog 通常需要 30-60 分钟。 +5. 将代理集成块添加到 `CLAUDE.md` / `AGENT.md`。 +6. 可选地将 `scripts/check-followups-drift.sh` 接入 pre-commit hook 以进行硬性 enforcement。 + +对于从临时跟踪迁移的 adopter:相同的流程,但步骤 4 可能需要决定哪些条目已经是 `closed` 或 `superseded` — 该分类是使注册表有用的关键。 + +--- + +## 参考实现 + +`StrangeDaysTech/sentinel` CHARTER-12,于 2026-05-06 合并: + +- 实现 PR: [sentinel#53](https://github.com/StrangeDaysTech/sentinel/pull/53)(注册表 + 脚本 + CLAUDE.md 添加)。 +- 关闭 PR: [sentinel#54](https://github.com/StrangeDaysTech/sentinel/pull/54)(合并后验证 + Charter 关闭)。 + +经验上下文: 47 个条目从 CHARTER-08 → CHARTER-11 回顾中播种(约 30 分钟的多代理 triage)。该链条展示了激发该模式的差距 — 没有注册表,操作员无法在不孤立地重新分类每个 Charter 的 follow-ups 的情况下查看"项目中所有待处理事项"。有了注册表,会话开始时的浏览就是一次文件读取。 + +--- + +## 未决问题 + +这些在 v0 中尚未解决。该模式的未来修订版本或 CLI helper 可能会处理它们: + +- **Bucket 分类启发式**。今天 `--apply` 将每个新条目转储到 `## Bucket: ready`;操作员手动重新分类。使用 AILOG `tags` 和 Charter `effort_estimate` 的启发式可以自动建议 bucket。 +- **Schema 验证**。注册表遵循一个隐式 schema;尚不存在 `.straymark/schemas/follow-ups-backlog.schema.v0.json`。今天的验证是人工审查。 +- **与审计周期的集成**。当 `straymark charter audit --merge-reports` 产生未在关闭前原子修复的真实 debt findings 时,这些 findings 仅存在于 `.straymark/audits//review.md` 中。它们不会自动流入中央注册表。自动浮现它们将关闭一个已知差距。 +- **`closed` 与 `superseded` 语义**。今天的差异在于解决工作是否显式引用了该条目。可能会出现更严格的约定。 +- **作为 `straymark followups` CLI 的结晶化**。一旦第二个 adopter 验证了该模式,framework 可以发布一个子命令,镜像现有的 `straymark charter` 三件套:`list` / `close` / `drift`。处于 v0 的 adopter(此模式)通过删除其本地脚本并切换代理指令进行迁移。 + +--- + +## 致谢 + +通过 [issue #111](https://github.com/StrangeDaysTech/straymark/issues/111) 由 Sentinel adopter 贡献。经验基础:`StrangeDaysTech/sentinel` 中的 CHARTER-08 → CHARTER-11 链。作者:Claude Opus 4.7,代表操作员 José Villaseñor Montfort。 + +--- + +## 相关 + +- [EMERGENT-OBSERVATION-DESIGN.md](EMERGENT-OBSERVATION-DESIGN.md) —— 元模式，此漂移检测约定在每 AILOG ↔ 注册表表面实例化了它。 +- [CHARTER-CHAIN-EVOLUTION.md](CHARTER-CHAIN-EVOLUTION.md) —— 在链级别（Pattern 1）和周期级别（Pattern 2）运作的姐妹模式。 +- [AGENT-RULES.md §3](AGENT-RULES.md) —— 可将 follow-ups 升级为专用债务条目的 TDE-vs-`R` 升级标准。 + +--- + +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/00-governance/i18n/zh-CN/GB-45438-LABELING-GUIDE.md b/.straymark/00-governance/i18n/zh-CN/GB-45438-LABELING-GUIDE.md new file mode 100644 index 0000000..40dde62 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/GB-45438-LABELING-GUIDE.md @@ -0,0 +1,118 @@ +# GB 45438 内容标识指南 — StrayMark + +> 根据 **GB 45438-2025**《网络安全技术 人工智能生成合成内容标识方法》及 CAC《人工智能生成合成内容标识办法》,填写 AILABEL 文档的实务指南。 + +**Languages**: [English](../../GB-45438-LABELING-GUIDE.md) | [Español](../es/GB-45438-LABELING-GUIDE.md) | 简体中文 + +--- + +## 状态 + +GB 45438-2025 是 **强制性** 国家技术标准,自 **2025-09-01** 起施行。CAC 办法是赋予该标准约束力的运营法规:任何范围内服务都必须实施 **显式**(可视)与 **隐式**(机器可读)双重标识。 + +服务在以下情况下属于范围:生成、合成或显著修改下列内容类型之任一: + +- 文本(对话补全、摘要、翻译) +- 图像(文生图、编辑、换脸、姿势编辑) +- 音频(声音克隆、TTS、音乐生成) +- 视频(文生视频、图生视频、深度合成) +- 虚拟场景(沉浸式 / 高拟真环境) + +如适用,在 MCARD 上设置 `gb45438_applicable: true` 并创建 AILABEL。验证规则 **CROSS-010** 强制执行此关联。 + +--- + +## 双轨标识 + +### 显式标识(可视) + +须可被普通用户感知。形式取决于媒介: + +| 媒介 | 可接受形式 | +|------|---------| +| 文本 | 在消息开始或结束的免责声明、banner、行内标签 | +| 图像 | 可视水印(角标、不透明度覆盖)、字幕 | +| 音频 | 片段开始的提示音、长片段的周期性口语披露 | +| 视频 | 持续水印 + 第一帧披露 | +| 虚拟场景 | 持续 HUD banner 或进入前提示 | + +显式标识应在合理观看条件下保持 **显著** 与 **可读**。 + +### 隐式标识(机器可读) + +在文件头嵌入元数据。标准 **至少** 强制: + +- `content_type` — `text` / `image` / `audio` / `video` / `virtual_scene` 之一 +- `service_provider_code` — CAC 备案后发放(关联到 CACFILE) +- `content_id` — 每件唯一标识符(推荐 UUIDv7 / ULID) + +StrayMark AILABEL 模板在第 3.2 节捕获这些字段。 + +GB 45438 **鼓励**(非强制)数字水印以增强持久性 — 见 AILABEL § 3.3。 + +--- + +## 选择元数据格式 + +| 格式 | 优势 | 劣势 | +|------|------|------| +| **C2PA**(内容凭证) | 行业标准,签名,生态广泛 | 较重;需要 PKI | +| **XMP** | 在图像/视频工具链成熟 | 常被社交平台剥离 | +| **EXIF** | 图像工具链通用 | 仅适用图像;易被剥离 | +| **Custom** | 字段定制 | 需分发者协助验证 | +| **None** | — | 不符合 GB 45438 | + +仅文本服务可将隐式元数据编码为 Unicode 私用区字符或响应外的 JSON 包封。在第 3.1 节记录选择。 + +--- + +## 持久性要求 + +GB 45438 期望隐式标识在文件被下载、导出或复制时持续。在 AILABEL 第 4 节提供证据: + +| 操作 | 测试 | +|------|------| +| 直接下载 | 从下载文件重新读取元数据 | +| 由其他工具重新导出 | 在第三方编辑器打开、保存、重新读取 | +| 截图 / 屏幕录制 | 即使元数据被剥离,水印也存活 | +| 重编码 | 鲁棒水印在 JPEG/MPEG 重编码后存活 | + +如显式标识无法存活(如纯文本截图),**隐式** 标识或 **鲁棒可视水印** 必须存活。 + +--- + +## 分发者义务 + +分发 AI 生成内容的平台必须: +- 当存在元数据时进行验证。 +- 识别合成内容时向观众显著呈现提示。 +- 不得移除或更改现有标识。 + +如服务分发上游提供者的内容,在 AILABEL 第 5 节记录如何履行这些义务。完成后设置 `gb45438_distributor_obligations_documented: true`。 + +--- + +## 与其他框架的关联 + +GB 45438 不孤立存在。它与以下框架交互: + +| 框架 | 交互 | +|------|------| +| **CAC 算法备案** | 隐式元数据中的 `service_provider_code` **由 CAC 在备案成功后发放**。AILABEL 必须引用 CACFILE。 | +| **EU AI Act 第50条** | 欧盟有平行透明度义务。单一标识设计可同时满足,但语言与验证界面可能不同。 | +| **TC260 v2.0** | `gb45438_applicable: true` 时,标识失败应作为 TC260RA 的 `application_risk` 出现。 | +| **C2PA / W3C 来源工作组** | 与 GB 45438 趋同的行业标准。选择 C2PA 可同时对齐全球与中国要求。 | + +--- + +## 合规检查 + +`straymark compliance --standard china-gb45438` 评估: + +| 检查 | 验证内容 | +|------|--------| +| GB45438-001 | 每个声明 `gb45438_applicable: true` 的 MCARD 都有对应 AILABEL | +| GB45438-002 | `gb45438_explicit_label_strategy` **与** `gb45438_implicit_metadata_format` 均已填充(不能仅选其一) | +| GB45438-003 | AILABEL 中已记录三个必填元数据字段 | + + diff --git a/.straymark/00-governance/i18n/zh-CN/GIT-BRANCHING-STRATEGY.md b/.straymark/00-governance/i18n/zh-CN/GIT-BRANCHING-STRATEGY.md new file mode 100644 index 0000000..0f7106a --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/GIT-BRANCHING-STRATEGY.md @@ -0,0 +1,94 @@ +# Git 分支策略 + +> **本项目 Git 工作流的参考文档。** +> 快速规则请参阅 CLAUDE.md 或 GEMINI.md 中的 Git 操作部分。 + +--- + +## 关键规则 + +**绝对不要直接提交到 `main` 分支。** + +所有变更必须通过功能/修复分支和 Pull Request 进行。这确保了代码审查、CI 验证和清晰的提交历史。 + +--- + +## 分支命名约定 + +| 前缀 | 用途 | 示例 | +| -------- | --------- | --------- | +| `feature/` | 新功能或增强 | `feature/export-excel` | +| `feat/` | feature 的别名 | `feat/folio-c5` | +| `fix/` | 缺陷修复 | `fix/report-form-tests` | +| `hotfix/` | 紧急生产修复 | `hotfix/auth-bypass` | +| `docs/` | 仅文档变更 | `docs/api-reference` | +| `refactor/` | 代码重构（无行为变更） | `refactor/catalog-service` | +| `test/` | 仅测试变更 | `test/bunit-coverage` | + +--- + +## 工作流 + +1. **开始工作前**，确认当前分支： + + ```bash + git branch --show-current + ``` + +2. **从最新的 `main` 创建分支**： + + ```bash + git checkout main + git pull origin main + git checkout -b fix/descriptive-name + ``` + +3. **按照约定式提交格式进行提交** + +4. **推送并创建 PR**： + + ```bash + git push -u origin fix/descriptive-name + gh pr create --title "fix: description" --body "..." + ``` + +5. **CI 通过后通过 PR 合并** - 绝不直接推送到 `main` + +--- + +## 约定式提交 + +在提交信息中使用语义化前缀： + +| 前缀 | 使用场景 | +| -------- | ---------- | +| `feat:` | 新功能 | +| `fix:` | 缺陷修复 | +| `docs:` | 仅文档 | +| `test:` | 添加或修复测试 | +| `refactor:` | 无行为变更的代码修改 | +| `chore:` | 维护、依赖、配置 | +| `perf:` | 性能改进 | + +--- + +## 恢复：如果意外提交到 Main + +如果有提交被错误地提交到了 `main`，而它们应该在一个分支上： + +```bash +# 用这些提交创建一个新分支 +git branch fix/accidental-commits + +# 将 main 重置为与远程一致 +git reset --hard origin/main + +# 切换到新分支并推送 +git checkout fix/accidental-commits +git push -u origin fix/accidental-commits +``` + +--- + +*StrayMark v1.0.0 | 最后更新：2025-01-30* +*[Strange Days Tech](https://strangedays.tech) — Because every change tells a story.* diff --git a/.straymark/00-governance/i18n/zh-CN/ISO-25010-2023-REFERENCE.md b/.straymark/00-governance/i18n/zh-CN/ISO-25010-2023-REFERENCE.md new file mode 100644 index 0000000..f26b2d1 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/ISO-25010-2023-REFERENCE.md @@ -0,0 +1,150 @@ +# ISO/IEC 25010:2023 — 软件质量参考 + +> **标准**: ISO/IEC 25010:2023 — Systems and software Quality Requirements and Evaluation (SQuaRE) — 产品质量模型 +> **替代**: ISO/IEC 25010:2011 +> **用途**: StrayMark 模板（ADR、REQ）中用于评估软件质量特性的参考文档。 + +--- + +## 质量特性（2023 vs 2011） + +2023 版本将模型从 8 个特性更新为 **9 个特性**，并进行了重要的重命名和重构。 + +| # | 特性（2023） | 原名称（2011） | 变更 | +|---|--------------|----------------|------| +| 1 | **功能适合性** | 功能适合性 | 无变化 | +| 2 | **性能效率** | 性能效率 | 无变化 | +| 3 | **兼容性** | 兼容性 | 无变化 | +| 4 | **交互能力** | 易用性 | 重命名 | +| 5 | **可靠性** | 可靠性 | 重构 | +| 6 | **安全性** | 安全性 | 新增子项：抗攻击性 | +| 7 | **可维护性** | 可维护性 | 无变化 | +| 8 | **灵活性** | 可移植性 | 重命名 | +| 9 | **安全（Safety）** | *（新）* | 新增特性 | + +--- + +## 详细特性与子特性 + +### 1. 功能适合性 + +产品提供满足明示和隐含需求的功能的程度。 + +| 子特性 | 描述 | +|--------|------| +| 功能完备性 | 功能集合覆盖所有规定任务和用户目标的程度 | +| 功能正确性 | 产品以所需精度提供正确结果的程度 | +| 功能恰当性 | 功能促进完成规定任务和目标的程度 | + +### 2. 性能效率 + +在规定条件下相对于所使用资源量的性能。 + +| 子特性 | 描述 | +|--------|------| +| 时间特性 | 响应、处理时间和吞吐率满足要求的程度 | +| 资源利用率 | 所使用资源的数量和类型满足要求的程度 | +| 容量 | 产品参数的最大限制满足要求的程度 | + +### 3. 兼容性 + +产品在共享同一环境的同时能够交换信息并执行其所需功能的程度。 + +| 子特性 | 描述 | +|--------|------| +| 共存性 | 产品在与其他产品共享公共环境和资源的同时高效执行其功能的程度 | +| 互操作性 | 两个或多个系统能够交换并使用信息的程度 | + +### 4. 交互能力 *（从易用性重命名）* + +产品能够被指定用户使用以实现具有有效性、效率和满意度的指定目标的程度。 + +| 子特性 | 描述 | 与 2011 的变化 | +|--------|------|----------------| +| 适合性可识别度 | 用户能够识别产品是否适合其需求的程度 | 无变化 | +| 可学习性 | 产品能够被用于以有效性、效率、无风险和满意度实现规定学习目标的程度 | 无变化 | +| 可操作性 | 产品具有使其易于操作和控制的属性的程度 | 无变化 | +| 用户错误保护 | 产品防止用户犯错的程度 | 无变化 | +| 用户参与度 | 产品提供吸引人且具有激励性的交互体验的程度 | 替代"用户界面美观性" | +| 包容性 | 产品能够被具有最广泛特征和能力的人群使用的程度 | 从"无障碍性"分离 | +| 用户辅助 | 产品向用户提供适当的帮助和指导的程度 | 从"无障碍性"分离 | +| 自描述性 | 产品呈现使其能力和使用方法立即显现的信息的程度 | 新增 | + +### 5. 可靠性 + +系统在规定条件下在规定时间段内执行规定功能的程度。 + +| 子特性 | 描述 | 与 2011 的变化 | +|--------|------|----------------| +| 无故障性 | 系统在正常条件下无故障运行的程度 | 替代"成熟度" | +| 可用性 | 系统在需要使用时处于运行和可访问状态的程度 | 无变化 | +| 容错性 | 系统在硬件或软件出现故障时仍按预期运行的程度 | 无变化 | +| 可恢复性 | 产品在中断或故障后能够恢复数据并重新建立期望状态的程度 | 无变化 | + +### 6. 安全性 + +产品保护信息和数据的程度。 + +| 子特性 | 描述 | 与 2011 的变化 | +|--------|------|----------------| +| 保密性 | 数据仅对授权访问者可访问的程度 | 无变化 | +| 完整性 | 系统防止对数据的未授权访问或修改的程度 | 无变化 | +| 不可抵赖性 | 行为或事件可被证明已发生的程度 | 无变化 | +| 可追溯性（可审计性） | 实体的行为可唯一追溯到该实体的程度 | 无变化 | +| 真实性 | 主体或资源的身份可被证明为其所声称的身份的程度 | 无变化 | +| 抗攻击性 | 产品抵抗来自未授权或恶意行为者攻击的程度 | 新增 | + +### 7. 可维护性 + +产品能够被修改的有效性和效率的程度。 + +| 子特性 | 描述 | +|--------|------| +| 模块化 | 系统由离散组件构成，使得对一个组件的修改对其他组件影响最小的程度 | +| 可重用性 | 资产能够被用于多个系统或用于构建其他资产的程度 | +| 可分析性 | 评估变更影响的有效性和效率的程度 | +| 可修改性 | 产品能够被有效且高效地修改而不引入缺陷的程度 | +| 可测试性 | 建立测试准则和执行测试的有效性和效率的程度 | + +### 8. 灵活性 *（从可移植性重命名）* + +产品能够适应不同或不断演变的硬件、软件或使用环境的程度。 + +| 子特性 | 描述 | 与 2011 的变化 | +|--------|------|----------------| +| 适应性 | 产品能够适应不同或不断演变环境的程度 | 无变化 | +| 易安装性 | 产品能够成功安装或卸载的有效性和效率的程度 | 无变化 | +| 易替换性 | 产品在同一环境中能够替换具有相同用途的其他指定产品的程度 | 无变化 | +| 可伸缩性 | 产品能够处理不断增长或缩减的工作负载的程度 | 新增 | + +### 9. 安全（Safety） *（新增特性）* + +产品对人员、业务、软件、财产或环境实现可接受风险水平的程度。 + +| 子特性 | 描述 | +|--------|------| +| 操作约束 | 产品将其操作约束在安全参数或状态范围内的程度 | +| 风险识别 | 产品识别可能影响安全的风险的程度 | +| 故障安全 | 产品在发生故障时自动置于安全操作模式或恢复到安全状态的程度 | +| 危险警告 | 产品提供危险警告的程度 | +| 安全集成 | 产品在与一个或多个组件集成期间和之后能够保持安全性的程度 | + +--- + +## 在 StrayMark 中的使用 + +- **TEMPLATE-REQ.md**: 非功能需求部分使用这 9 个特性作为类别 +- **TEMPLATE-ADR.md**: 后果部分根据相关质量特性评估决策 +- **TEMPLATE-TES.md**: 测试规划将质量特性视为覆盖维度 + +## 需要记住的关键变化 + +在审查或创建 StrayMark 文档时： + +1. 使用 **"交互能力"** 而不是"易用性" +2. 使用 **"灵活性"** 而不是"可移植性" +3. 始终将 **"安全（Safety）"** 视为质量维度，尤其对 AI 系统 +4. **"抗攻击性"**（安全性下）与威胁评估相关 +5. **"可伸缩性"**（灵活性下）现在是正式的子特性 + + diff --git a/.straymark/00-governance/i18n/zh-CN/MANAGEMENT-REVIEW-TEMPLATE.md b/.straymark/00-governance/i18n/zh-CN/MANAGEMENT-REVIEW-TEMPLATE.md new file mode 100644 index 0000000..1934565 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/MANAGEMENT-REVIEW-TEMPLATE.md @@ -0,0 +1,183 @@ +# 管理评审模板 + +> **对齐标准**：ISO/IEC 42001:2023 条款 9.3 — 管理评审 +> +> 本模板为 AI 管理系统的定期管理评审提供结构化框架。它确保按照条款 9.3 的要求考虑所有必需输入，并记录决策和行动以便后续跟踪。 +> +> **这是一个模板** — 每个评审周期完成一个实例，并归档到项目记录中。 + +--- + +## 评审元数据 + +| 字段 | 值 | +|------|------| +| **评审日期** | [YYYY-MM-DD] | +| **参会人员** | [姓名和职位] | +| **评审周期** | [开始日期] 至 [结束日期] | +| **下次评审日期** | [YYYY-MM-DD] | +| **主持人** | [姓名] | +| **记录人** | [姓名] | + +--- + +## 议程 + +### 1. 上次评审行动项状态 + +> ISO 42001 条款 9.3 输入 (a)：上次管理评审行动项的状态。 + +| 行动项 | 负责人 | 截止日期 | 状态 | 备注 | +|--------|--------|----------|------|------| +| [上次评审的行动项] | [负责人] | [日期] | [Open / In progress / Closed] | [备注] | +| [上次评审的行动项] | [负责人] | [日期] | [Open / In progress / Closed] | [备注] | + +**讨论记录**：[记录有关逾期或未完成行动项的讨论] + +--- + +### 2. 外部和内部问题的变化 + +> ISO 42001 条款 9.3 输入 (b)：与 AI 管理系统相关的外部和内部问题的变化。 + +#### 2.1 法规变化 + +| 变化 | 影响 | 所需行动 | 负责人 | +|------|------|----------|--------| +| [新法规或修订] | [对 AI 系统的影响] | [需要的行动] | [负责人] | + +#### 2.2 组织变化 + +| 变化 | 影响 | 所需行动 | 负责人 | +|------|------|----------|--------| +| [团队重组、新系统、战略变更] | [对治理的影响] | [需要的行动] | [负责人] | + +#### 2.3 技术变化 + +| 变化 | 影响 | 所需行动 | 负责人 | +|------|------|----------|--------| +| [新 AI 能力、供应商变更、基础设施更新] | [对风险概况的影响] | [需要的行动] | [负责人] | + +**讨论记录**：[记录有关重大变化的讨论] + +--- + +### 3. AI 系统性能信息 + +> ISO 42001 条款 9.3 输入 (c)：AI 管理系统性能信息。 + +#### 3.1 治理指标（来自 AI-KPIS.md） + +| KPI | 目标 | 当前值 | 上期值 | 趋势 | 状态 | +|-----|------|--------|--------|------|------| +| 文档覆盖率 | > 80% | [值] | [值] | [上升/下降/稳定] | [达标 / 有风险 / 低于目标] | +| 审核合规率 | 100% | [值] | [值] | [上升/下降/稳定] | [达标 / 有风险 / 低于目标] | +| 平均文档编写时间 | < 1 天 | [值] | [值] | [上升/下降/稳定] | [达标 / 有风险 / 低于目标] | +| 风险分布 | < 20% high/critical | [值] | [值] | [上升/下降/稳定] | [达标 / 有风险 / 低于目标] | +| 事件响应时间 | < 24 小时 | [值] | [值] | [上升/下降/稳定] | [达标 / 有风险 / 低于目标] | +| 合规评分 | > 75% | [值] | [值] | [上升/下降/稳定] | [达标 / 有风险 / 低于目标] | + +> **来源**：在评审前运行 `straymark metrics` 以收集当前值。 + +#### 3.2 AI 系统状态（来自 AI-LIFECYCLE-TRACKER.md） + +| 系统 | 阶段 | 风险级别 | 本期问题 | +|------|------|----------|----------| +| [系统名称] | [当前阶段] | [风险级别] | [问题摘要] | + +**讨论记录**：[记录有关性能趋势和系统健康状况的讨论] + +--- + +### 4. 审计结果 + +> ISO 42001 条款 9.3 输入 (d)：审计结果。 + +#### 4.1 内部审计发现 + +| 发现 ID | 描述 | 严重程度 | 纠正措施 | 状态 | +|---------|------|----------|----------|------| +| [ID] | [发现描述] | [Major / Minor / Observation] | [已采取或计划的措施] | [Open / Closed] | + +#### 4.2 外部审计发现（如适用） + +| 发现 ID | 描述 | 严重程度 | 纠正措施 | 状态 | +|---------|------|----------|----------|------| +| [ID] | [发现描述] | [严重程度] | [已采取或计划的措施] | [Open / Closed] | + +> **来源**：在评审前运行 `straymark compliance --all` 以生成合规报告。 + +**讨论记录**：[记录有关审计发现和整改进展的讨论] + +--- + +### 5. AI 目标达成情况 + +> ISO 42001 条款 9.3 输入 (e)：AI 目标达成信息。 + +| 目标 | 指标 | 当前状态 | 是否按计划 | 备注 | +|------|------|----------|-----------|------| +| [治理策略 §3.2 中的目标] | [指标] | [状态] | [是 / 有风险 / 否] | [备注] | + +> **参考**：目标定义在 AI-GOVERNANCE-POLICY.md 第 3.2 节（AI 目标）中。 + +**讨论记录**：[记录有关目标达成情况及所需调整的讨论] + +--- + +### 6. 不符合项和纠正措施 + +> ISO 42001 条款 9.3 输入 (f)：不符合项和纠正措施。 + +| 不符合项 ID | 描述 | 根本原因 | 纠正措施 | 状态 | +|-------------|------|----------|----------|------| +| NC-[NNN] | [不符合项描述] | [根本原因分析] | [已采取或计划的纠正措施] | [Open / In progress / Closed / Verified] | + +> **来源**：StrayMark 中的 INC 文档和 `straymark compliance` 失败项。 + +**讨论记录**：[记录有关反复出现的问题和系统性问题的讨论] + +--- + +### 7. 改进机会 + +> ISO 42001 条款 9.3 输入 (g)：持续改进的机会。 + +| 改进项 | 优先级 | 负责人 | 截止日期 | 预期收益 | +|--------|--------|--------|----------|----------| +| [改进描述] | [High / Medium / Low] | [负责人] | [日期] | [预期收益] | + +**讨论记录**：[记录有关改进优先级和资源分配的讨论] + +--- + +## 决策和行动 + +> ISO 42001 条款 9.3 输出：与持续改进机会相关的决策和行动，以及 AI 管理系统变更需求。 + +| 行动 | 负责人 | 截止日期 | 状态 | 优先级 | +|------|--------|----------|------|--------| +| [行动描述] | [负责人] | [YYYY-MM-DD] | [Not started / In progress / Complete] | [High / Medium / Low] | + +--- + +## 备注 + +[评审会议中的额外说明、观察或背景信息] + +--- + +## 审批 + +| 角色 | 姓名 | 签名 | 日期 | +|------|------|------|------| +| 评审主持人 | [姓名] | | [日期] | +| AI 治理负责人 | [姓名] | | [日期] | +| 管理层代表 | [姓名] | | [日期] | + +--- + +*管理评审模板 — StrayMark 框架* +*对齐 ISO/IEC 42001:2023 条款 9.3* + + diff --git a/.straymark/00-governance/i18n/zh-CN/OBSERVABILITY-GUIDE.md b/.straymark/00-governance/i18n/zh-CN/OBSERVABILITY-GUIDE.md new file mode 100644 index 0000000..636a7d8 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/OBSERVABILITY-GUIDE.md @@ -0,0 +1,266 @@ +# 可观测性指南 — StrayMark 项目的 OpenTelemetry 集成 + +> **本指南为可选内容。** 当您的项目使用 OpenTelemetry 进行系统埋点时可采用本指南。 +> 它是对现有 StrayMark 治理文档的补充，不替代任何现有文档。 + +--- + +## 1. 范围和目的 + +本指南为选择采用 OpenTelemetry (OTel) 作为可观测性框架的项目提供结构化方法。它**不是强制性的** — 当团队决定对其系统进行埋点时才生效。 + +本指南涵盖： + +- **信号**：收集哪些遥测信号以及它们之间的关系 +- **配置**：资源属性、上下文传播和 Collector 管道 +- **数据策略**：可以和不可以采集的内容、数据保留和安全 +- **StrayMark 集成**：可观测性工作如何映射到现有文档类型 + +> **何时启用本指南**：当至少一个服务将通过 OpenTelemetry 发送追踪、指标或结构化日志时，将本指南纳入项目治理。在 AIDEC 或 ADR 中记录该决策。 + +--- + +## 2. 信号和关联 + +OpenTelemetry 定义了三种核心信号。有效的可观测性需要三者兼备，并通过共享标识符进行关联。 + +| 信号 | 用途 | 关键属性 | 关联方式 | +|------|------|----------|----------| +| **追踪（Traces）** | 跨服务的分布式请求流 | `trace_id`、`span_id`、业务属性（如 `user.tier`、`order.id`） | 通过 `traceparent` 的父子 span 关系 | +| **指标（Metrics）** | 随时间变化的定量度量 | 延迟（直方图）、错误率（计数器）、饱和度（仪表）、吞吐量（计数器） | Exemplar 将指标样本链接到 `trace_id` | +| **日志（Logs）** | 具有结构化上下文的离散事件 | `severity`、`body`、应用程序特定字段 | 将 `trace_id` 和 `span_id` 注入日志记录 | + +### 信号关联方式 + +`trace_id` 是通用关联键： + +- **日志到追踪**：每条日志记录携带其活跃上下文的 `trace_id` 和 `span_id`，允许从日志行直接导航到产生它的追踪。 +- **追踪到指标**：指标数据点上的 Exemplar 引用 `trace_id`，将聚合度量链接回特定请求。 +- **指标到日志**：指标告警识别时间窗口；该窗口内的关联日志共享相同的资源属性，支持根因分析。 + +> **建议**：始终确保日志输出中包含 `trace_id` 和 `span_id`。没有这种关联，三种信号将成为孤立的数据孤岛。 + +--- + +## 3. 最低资源属性 + +资源属性标识遥测数据的来源。在应用程序启动时配置一次；它们适用于所有信号。 + +| 属性 | 要求 | 说明 | 示例 | +|------|------|------|------| +| `service.name` | **必需** | 服务的逻辑名称 | `payment-api` | +| `service.version` | **必需** | 已部署服务的版本 | `2.4.1` | +| `deployment.environment` | **必需** | 部署目标 | `production`、`staging`、`development` | +| `service.instance.id` | 建议 | 实例的唯一标识符 | `pod-abc123`、`i-0a1b2c3d` | + +> **注意**：这些属性与 [OpenTelemetry 资源语义约定](https://opentelemetry.io/docs/specs/semconv/resource/)对齐。根据您的部署模型，按需使用其他语义约定属性（如 `host.name`、`cloud.region`、`k8s.namespace.name`）。 + +--- + +## 4. 上下文传播 + +上下文传播确保单个请求可以跨服务边界进行追踪。StrayMark 项目应使用 **W3C Trace Context** 标准。 + +### 头部信息 + +- **`traceparent`**：携带 `trace_id`、`span_id` 和追踪标志。这是最低要求的头部信息。 +- **`tracestate`**：携带供应商特定或应用程序特定的键值对。可选，但在多供应商环境中很有用。 + +### 按传输方式的传播 + +| 传输方式 | 传播方法 | 备注 | +|----------|----------|------| +| HTTP（同步） | `traceparent` / `tracestate` 头部 | 大多数 SDK 自动注入 | +| 消息队列（Kafka、RabbitMQ、SQS） | 消息头部或属性 | 需要显式埋点；将 `traceparent` 设置为消息属性 | +| 异步/后台任务 | 任务元数据或负载 | 将 `traceparent` 作为任务信封的一部分传递；在工作端恢复上下文 | +| gRPC | 元数据头部 | 大多数 OTel gRPC 拦截器自动埋点 | + +### 自动埋点 vs 手动埋点 + +- **自动埋点**（代理、库）：自动处理 HTTP 和 gRPC 传播。建议以此作为起点。 +- **手动埋点**：消息队列、后台任务和自定义协议需要手动埋点。开发人员必须显式注入和提取上下文。 + +> **建议**：从 HTTP/gRPC 的自动埋点开始。逐步为基于消息和异步的流程添加手动埋点。在 AILOG 中记录每次埋点变更。 + +--- + +## 5. Collector 管道架构 + +OpenTelemetry Collector 作为应用程序和后端之间的中央遥测处理网关。以清晰的关注点分离来构建它。 + +### 管道阶段 + +1. **接收器（Receivers）**：通过 OTLP 接收来自应用程序的遥测数据（gRPC 端口 4317，HTTP 端口 4318）。 +2. **处理器（Processors）**：在导出前转换、过滤和丰富数据。 + - **批处理器（Batch Processor）**：将数据分组为批次以高效导出。 + - **脱敏处理器（Redaction Processor）**：移除或屏蔽敏感属性（见第 7 节）。 + - **资源处理器（Resource Processor）**：使用额外资源属性丰富数据。 +3. **导出器（Exporters）**：将处理后的数据发送到可观测性后端（如 Jaeger、Prometheus、Loki、Grafana Cloud、Datadog）。 + +### 管道图 + +```mermaid +flowchart LR + App[Application] -->|OTLP| R[Receiver] + R --> P1[Batch Processor] + P1 --> P2[Redaction Processor] + P2 --> E[Exporter] + E --> B[Backend] +``` + +### 独立管道 + +为每种信号类型配置独立的管道： + +| 管道 | 接收器 | 处理器 | 导出器 | +|------|--------|--------|--------| +| **追踪** | `otlp` | `batch`、`redaction`、`resource` | 追踪后端（如 Jaeger、Tempo） | +| **指标** | `otlp` | `batch`、`resource` | 指标后端（如 Prometheus、Mimir） | +| **日志** | `otlp` | `batch`、`redaction`、`resource` | 日志后端（如 Loki、Elasticsearch） | + +> **建议**：在生产环境中将 Collector 作为 sidecar 或 daemon 运行。避免从应用程序直接向后端发送遥测数据 — Collector 提供缓冲、重试和安全执行。 + +--- + +## 6. 采样和保留 + +采样控制收集的遥测数据量。正确的策略需要在成本和可观测性覆盖之间取得平衡。 + +### 采样策略 + +| 策略 | 使用场景 | 权衡 | +|------|----------|------| +| **头采样（Head sampling）** | 可预测的流量、成本敏感环境 | 在追踪开始时做出决策；配置简单；可能遗漏罕见错误 | +| **尾采样（Tail sampling）** | 需要捕获所有错误和慢追踪 | 在追踪完成后做出决策；捕获重要追踪；需要 Collector 有内存来保存待处理追踪 | +| **全量采集（Always-on）**（100%） | 低流量服务、开发、预发布 | 完全可见性；存储成本高；不适合高吞吐量生产环境 | +| **速率限制（Rate limiting）** | 保护后端免受突发流量影响 | 按秒限制数据量；可与其他策略配合使用 | + +### 保留策略 + +| 环境 | 最短保留期 | 原因 | +|------|-----------|------| +| **生产环境** | 30 天 | 事件调查、趋势分析、合规 | +| **预发布环境** | 7 天 | 发布前验证和调试 | +| **开发环境** | 1 天 | 快速迭代；无需长期存储 | + +> **建议**：大多数生产服务使用头采样。在 Collector 层添加尾采样，以确保错误（HTTP 5xx、异常）和慢追踪（超过 P99 延迟）始终被捕获，不受头采样率的影响。 + +--- + +## 7. 数据策略和安全 + +> **重要**：绝不在 OpenTelemetry 属性、span 事件或日志正文中采集个人身份信息 (PII)、认证令牌、API 密钥、密码或机密信息。违规可能违反 GDPR、内部安全策略和用户信任。 + +### 策略要求 + +| 策略 | 要求 | 实施方式 | +|------|------|----------| +| **属性允许列表** | 仅允许捕获明确许可的属性 | 在 Collector 配置中维护允许列表；拒绝未列出的属性 | +| **PII 禁止** | span、指标标签或日志正文中不得包含 PII | 脱敏处理器剥离匹配 PII 模式的字段（电子邮件、IP、信用卡） | +| **传输加密** | 应用程序、Collector 和后端之间的所有遥测数据加密 | OTLP gRPC/HTTP 使用 TLS；生产环境建议 mTLS | +| **静态加密** | 后端存储的遥测数据加密 | 后端级加密；与基础设施团队确认 | +| **访问控制** | 基于角色的遥测数据访问 | 按环境分离访问（生产 vs 预发布）；将生产追踪访问限制为值班人员和事件响应人员 | +| **自动清洗** | Collector 级脱敏作为安全兜底 | 配置 `redaction` 处理器，设置令牌、机密信息和 PII 的匹配模式 | + +### 允许列表方法 + +与其试图阻止每个敏感字段，不如定义一个明确的允许属性列表： + +1. 从 OTel 语义约定属性开始（这些在设计上是安全的）。 +2. 仅在审查后添加业务属性（例如 `order.id` 可接受；`user.email` 不可接受）。 +3. 在 Collector 配置中记录允许列表，并在可观测性变更时进行审查。 + +> **建议**：将 Collector 的脱敏处理器视为安全兜底，而非主要防线。主要防线是开发人员的意识和对埋点变更的代码审查。 + +--- + +## 8. StrayMark 集成 + +可观测性工作产生的制品必须在 StrayMark 框架内进行记录。使用以下映射来确定需要创建或更新的文档类型。 + +| 变更 | StrayMark 文档 | 备注 | +|------|--------------|------| +| 埋点变更（新 span、属性） | **AILOG** | 标签：`observabilidad` | +| 后端选型决策 | **AIDEC** 或 **ADR** | 取决于范围；AI 辅助决策用 AIDEC，架构决策用 ADR | +| 可观测性需求 | **REQ** | 章节：可观测性需求 | +| 传播测试 | **TES** | 章节：可观测性测试 | +| 包含追踪证据的事件 | **INC** | 在事件记录中包含 `trace_id`、`span_id` | +| 埋点债务 | **TDE** | 跟踪缺失或不完整的埋点技术债务 | +| 遥测隐私评估 | **ETH** | 数据隐私章节；评估遥测采集的内容 | +| 遥测管道安全 | **SEC** | 评估 Collector 安全性、访问控制、加密 | + +> **建议**：进行埋点变更时，始终创建一个带有 `observabilidad` 标签的 AILOG 条目。这提供了正在观测什么以及为什么观测的审计轨迹。 + +--- + +## 9. 采用路线图 + +逐步采用 OpenTelemetry。每个阶段建立在前一个阶段之上，并产生特定的 StrayMark 文档。 + +### 阶段 0 — 决策 + +- 创建 **AIDEC** 或 **ADR** 记录采用 OpenTelemetry 的决策。 +- 评估和选择可观测性后端。 +- 定义初始数据策略（允许列表、保留、访问）。 +- 如果遥测可能采集用户相关数据，创建 **ETH**。 + +### 阶段 1 — 最小化埋点 + +- 对关键端点进行埋点（API 入口点、关键业务操作）。 +- 配置资源属性：`service.name`、`service.version`、`deployment.environment`。 +- 部署 OpenTelemetry Collector 并配置基本管道（batch + export）。 +- 创建包含初始可观测性需求的 **REQ**。 +- 在 **AILOG** 条目中记录埋点变更。 + +### 阶段 2 — 全面覆盖 + +- 将埋点扩展到所有服务和异步流程。 +- 在所有传输方式上配置 W3C Trace Context 传播。 +- 在 Collector 管道中添加脱敏处理器。 +- 实施采样策略（头采样 + 尾采样）。 +- 创建验证追踪传播和日志关联的 **TES** 条目。 + +### 阶段 3 — 运营集成 + +- 将追踪证据集成到 **INC** 记录中（事件的 `trace_id`、`span_id`）。 +- 在 **REQ** 文档中定义可观测性 SLO（例如"P99 延迟 < 200ms"）。 +- 在 CI 中自动化传播测试（在 **TES** 中引用）。 +- 将埋点缺口作为 **TDE** 条目进行跟踪。 +- 每季度审查和更新属性允许列表。 + +--- + +## 10. 检查清单 + +使用此检查清单验证项目的 OpenTelemetry 集成是否完整且符合 StrayMark 治理要求。 + +- [ ] **AIDEC/ADR** 记录 OTel 采用决策和后端选型 +- [ ] **REQ** 包含可观测性需求和 SLO +- [ ] 已配置资源属性（`service.name`、`service.version`、`deployment.environment`） +- [ ] 已验证所有传输方式上的 W3C Trace Context 传播 +- [ ] 已在 Collector 管道中配置敏感数据脱敏 +- [ ] **TES** 验证追踪传播和日志关联 +- [ ] **INC** 模板已更新，包含 `trace_id` / `span_id` 字段 +- [ ] 已为埋点变更创建带有 `observabilidad` 标签的 **AILOG** +- [ ] **ETH** 涵盖遥测数据隐私和 PII 评估 + +--- + +## 法规对齐 + +OpenTelemetry 埋点支持遵循与 StrayMark 项目相关的多个法规和标准框架。 + +| 标准 | 参考 | 相关性 | +|------|------|--------| +| **EU AI Act** | Art. 72（上市后监控） | OTel 提供 AI 系统持续上市后监控所需的监控基础设施 | +| **NIST AI RMF** | MEASURE 功能 | 通过 OTel 收集的运营指标作为 AI 风险管理的度量工具 | +| **GDPR** | Art. 5（数据最小化） | 遥测不得采集 PII；允许列表方法和脱敏处理器执行数据最小化 | +| **ISO/IEC 25010:2023** | 可靠性、性能效率 | OTel 追踪和指标为可观测的质量特征提供证据 | +| **ISO/IEC 42001** | A.6.2.6（运行和监控） | 来自 OTel 的持续运营证据支持 AI 管理系统监控要求 | +| **ISO/IEC 42001** | A.5.2（风险评估） | 通过 OTel 收集的运营数据为持续的风险评估和缓解提供信息 | + +> **建议**：在准备审计或合规审查时，将 OTel 数据导出与 StrayMark 文档（REQ、INC、ETH）一起使用，以证明持续监控和数据治理。 + +--- + + diff --git a/.straymark/00-governance/i18n/zh-CN/PIPL-PIPIA-GUIDE.md b/.straymark/00-governance/i18n/zh-CN/PIPL-PIPIA-GUIDE.md new file mode 100644 index 0000000..5ed1373 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/PIPL-PIPIA-GUIDE.md @@ -0,0 +1,142 @@ +# PIPL / PIPIA 指南 — StrayMark + +> 根据《中华人民共和国个人信息保护法》(PIPL)第55-56条,完成个人信息保护影响评估(PIPIA)的实务指南。 + +**Languages**: [English](../../PIPL-PIPIA-GUIDE.md) | [Español](../es/PIPL-PIPIA-GUIDE.md) | 简体中文 + +--- + +## 何时需要 PIPIA + +根据 **PIPL 第55条**,在以下情形之前必须进行 PIPIA: + +1. 处理 **敏感个人信息**(第28条:生物识别、宗教信仰、特定身份、医疗健康、金融账户、行踪轨迹、不满14周岁未成年人个人信息)。 +2. 利用个人信息进行 **自动化决策**。 +3. 委托处理 / 向其他个人信息处理者提供 / 公开个人信息。 +4. 跨境提供个人信息至中国大陆境外。 +5. 其他对个人有重大影响的处理活动。 + +如适用,在相关 ETH / MCARD / AILOG 上设置 `pipl_applicable: true` 并创建 PIPIA 文档。验证规则 **CROSS-005** 强制执行此关联。 + +--- + +## PIPIA 与 DPIA 对比 + +PIPIA(中国)与 DPIA(欧盟 GDPR 第35条)在概念上重叠,但细节不同: + +| 方面 | DPIA(GDPR) | PIPIA(PIPL) | +|------|-------------|-------------| +| 法定依据 | GDPR 第35条 | PIPL 第55-56条 | +| 触发阈值 | "高风险" | 第55条所列五种情形之任一 | +| 必备要素 | 必要性、对数据主体的风险、缓解、DPO 协商 | 合法/正当/必要性、个人权益影响、安全风险、保护措施的相称性 | +| 留存 | GDPR 未明确 | **至少 3 年**(第56条) | +| 当局协商 | 残余风险高时强制 | 跨境传输需省级网信部门协商 | + +如同时受 GDPR 与 PIPL 约束,可: +- 维护 DPIA 作为主文档。 +- 维护 PIPIA 通过 `related: [DPIA-...]` 反向引用 DPIA,并补充 PIPL 特有要素。 + +DPIA 模板已包含 *Cross-reference: PIPIA* 部分,在 `pipl_applicable: true` 时反向指向。 + +--- + +## PIPIA 报告的三个必备要素(第56条) + +PIPIA 必须涵盖: + +### 1. 合法性 / 正当性 / 必要性 + +- **合法**:依据 PIPL 第13条确定法律依据(同意、履行合同、法定义务、应急、新闻报道、公共利益、已公开信息)。 +- **正当**:目的清晰、合理且已披露。 +- **必要**:为达成目的而处理最小数据。 + +### 2. 个人权益影响 + 安全风险 + +- 将每项 PIPL 权利(第44-47条,加第24条自动化决策退出)映射为可能性 / 严重程度 / 缓解。 +- 识别保密性、完整性、可用性风险。使用与 StrayMark `risk_level` 相同的评级(低/中/高)。 + +### 3. 保护措施的相称性 + +- 证明措施 **合法、有效、与风险程度相称**。 +- 记录每项措施后的残余风险。 + +--- + +## 跨境传输(PIPL 第38-40条) + +跨境传输需以下机制 **之一**: + +| 机制 | 适用 | +|------|------| +| **CAC 安全评估** | 关键信息基础设施运营者(CIIO);处理 ≥ 100 万人个人信息;任何连续 12 个月内累计跨境传输个人信息 ≥ 10 万人或敏感个人信息 ≥ 1 万人 | +| **个人信息保护认证** | 自愿替代;由认证机构颁发 | +| **标准合同** | 向省级网信部门备案;适合较小数量 | + +StrayMark 当前不将这些建模为结构化字段(超出 `pipl_cross_border_transfer: true`)— 在 PIPIA 模板的 *Cross-Border Transfer Analysis* 部分记录所选机制。 + +--- + +## 留存 + +根据第56条,PIPIA 报告及相关 "处理情况记录" 须 **至少留存三年**。设置 `pipl_retention_until: YYYY-MM-DD` 至少为 `created` 之后 3 年。**TYPE-003** 验证强制执行。 + +```yaml +created: 2026-04-25 +pipl_retention_until: 2029-04-25 # 恰好 3 年 — 允许的最小值 +``` + +--- + +## 敏感个人信息触发 + +以下类别需特殊保护(第28条): + +- 生物识别(指纹、人脸、声纹、步态) +- 宗教信仰 +- 特定身份 +- 医疗健康 +- 金融账户 +- 行踪轨迹 +- 不满 14 周岁未成年人个人信息 + +处理需 **单独同意** 并 PIPIA。如模型在训练或推理中使用以上任一: +- 设置 `pipl_sensitive_data: true` +- 在 PIPIA 的 *保护措施* 部分记录缓解 +- 交叉引用相关 MCARD 的 `## Training Data` 部分 + +--- + +## 个人信息保护负责人(PIPL 第52条) + +处理 **超过 100 万** 个人信息的处理者,需指定个人信息保护负责人。如适用: +- 协商后在 PIPIA 上设置 `dpo_consulted: true` +- 在 *协商* 部分记录意见 + +--- + +## 实例:客户聊天机器人 + +部署在中国大陆的 SaaS 聊天机器人: +- 存储对话历史(个人信息) +- 使用 LLM 自动响应(自动化决策) +- 部分查询发往境外推理端点(跨境) + +**触发**:1、2、4 → 需 PIPIA。 + +**Frontmatter**: +```yaml +id: PIPIA-2026-04-25-001 +pipl_applicable: true +pipl_article_55_trigger: cross_border +pipl_sensitive_data: false +pipl_cross_border_transfer: true +pipl_retention_until: 2029-04-25 +related: + - MCARD-2026-04-25-001 + - TC260RA-2026-04-25-001 + - DPIA-2026-04-25-001 +``` + +**重点章节**:跨境分析、自动化决策(第24条退出)、法律依据(通常为同意)、接收方保障。 + + diff --git a/.straymark/00-governance/i18n/zh-CN/PRINCIPLES.md b/.straymark/00-governance/i18n/zh-CN/PRINCIPLES.md new file mode 100644 index 0000000..e6bc078 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/PRINCIPLES.md @@ -0,0 +1,91 @@ +# 指导原则 - StrayMark + +> 这些原则指导项目中的所有文档决策。 + +**语言**: [English](../../PRINCIPLES.md) | [Español](../es/PRINCIPLES.md) | 简体中文 + +--- + +## 1. 完全可追溯性 + +> **"任何重大变更都必须有文档记录的痕迹。"** + +每个影响业务逻辑、安全或架构的变更都必须记录： +- 变更了什么 +- 为什么变更 +- 谁（人类或代理）做出了变更 +- 何时变更 + +--- + +## 2. AI 代理透明度 + +在项目中工作的 AI 代理必须： +- 在其生成的每份文档中清楚地标识自身 +- 声明其对决策的置信度级别 +- 在适当时请求人工审核 +- 不隐瞒相关信息 + +--- + +## 3. 强制人工审核 + +某些类型的变更**始终**需要人工批准： +- 伦理决策 (ETH) +- 关键安全变更 +- 不可逆修改 +- `confidence: low` 的决策 + +--- + +## 4. 文档即代码 + +- 文档与代码一起进行版本控制 +- 遵循严格的命名约定 +- 使用可读格式（Markdown + YAML frontmatter） +- 可以自动处理 + +--- + +## 5. 最小可行，最大有用 + +- 记录必要的内容，不多不少 +- 避免重复信息 +- 保持文档更新或归档 +- 优先清晰而非详尽 + +--- + +## 6. 职责分离 + +| 人类 | AI 代理 | +|------|---------| +| 验证需求 | 提出需求 | +| 批准伦理决策 | 创建伦理草稿 | +| 确定技术债务优先级 | 识别技术债务 | +| 定义架构 | 记录实现 | + +--- + +## 7. 默认安全 + +- **绝不**记录凭据、令牌或机密信息 +- 将安全变更标记为 `risk_level: high` +- 认证/授权变更需要审核 +- 记录隐私考量 (GDPR/PII) + +--- + +## 8. 跨源不一致浮现 + +> **"当两个规范源不一致时，在继续之前先浮现。"** + +当智能体检测到 StrayMark 文档中两个规范源之间的实质性分歧（spec ↔ 代码、AILOG `§Risk` ↔ TDE backlog、ADR ↔ 实现、Charter 声明范围 ↔ commits 等）时，必须在继续被询问的任务之前浮现该分歧。 + +StrayMark 文档经过审慎设计，以使这些分歧可检测：形式化交叉引用（frontmatter 字段、规范章节、稳定 ID）+ 超越任务的文化浮现许可。智能体的角色是消费该基础设施并报告其所见。 + +参见 [`EMERGENT-OBSERVATION-DESIGN.md`](EMERGENT-OBSERVATION-DESIGN.md) 以了解元模式和现有应用的金字塔。 + +--- + +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/00-governance/i18n/zh-CN/QUICK-REFERENCE.md b/.straymark/00-governance/i18n/zh-CN/QUICK-REFERENCE.md new file mode 100644 index 0000000..c29c6db --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/QUICK-REFERENCE.md @@ -0,0 +1,219 @@ +# StrayMark - 快速参考 + +> AI 代理和开发者的单页参考。 +> +> **这是一份派生文档** — DOCUMENTATION-POLICY.md 是权威来源。 + +**语言**: [English](../../QUICK-REFERENCE.md) | [Español](../es/QUICK-REFERENCE.md) | 简体中文 + +--- + +## 语言配置 + +**文件**：`.straymark/config.yml` + +```yaml +language: en # Options: en, es (default: en) +``` + +| 语言 | 模板路径 | +|------|----------| +| `en` | `.straymark/templates/TEMPLATE-*.md` | +| `es` | `.straymark/templates/i18n/es/TEMPLATE-*.md` | + +--- + +## 命名约定 + +``` +[TYPE]-[YYYY-MM-DD]-[NNN]-[description].md +``` + +**示例**：`AILOG-2026-03-25-001-implement-oauth.md` + +--- + +## 文档类型（12 种） + +### 核心类型（8 种） + +| 类型 | 名称 | 目录 | 代理自主权 | +|------|------|------|-----------| +| `AILOG` | AI 操作日志 | `07-ai-audit/agent-logs/` | 自由创建 | +| `AIDEC` | AI 决策 | `07-ai-audit/decisions/` | 自由创建 | +| `ETH` | 伦理审查 | `07-ai-audit/ethical-reviews/` | 仅草稿 | +| `ADR` | 架构决策 | `02-design/decisions/` | 需要审核 | +| `REQ` | 需求 | `01-requirements/` | 提议 | +| `TES` | 测试计划 | `04-testing/` | 提议 | +| `INC` | 事故事后分析 | `05-operations/incidents/` | 协助 | +| `TDE` | 技术债务 | `06-evolution/technical-debt/` | 识别 | + +### 扩展类型（4 种） + +| 类型 | 名称 | 目录 | 代理自主权 | +|------|------|------|-----------| +| `SEC` | 安全评估 | `08-security/` | 草稿 → 批准（始终） | +| `MCARD` | 模型/系统卡 | `09-ai-models/` | 草稿 → 批准（始终） | +| `SBOM` | 软件物料清单 | `07-ai-audit/` | 自由创建 | +| `DPIA` | 数据保护影响评估 | `07-ai-audit/ethical-reviews/` | 草稿 → 批准（始终） | + +### 有界工作单元 — Charter + +Charter **不是**文档类型——它包裹一个跨多个会话的实施块。文件名使用顺序前缀（`NN-slug.md`），而不是日期前缀。生命周期：`declared` → `in-progress` → `closed`。 + +| 概念 | 目录 | 代理自主权 | +|------|------|-----------| +| `Charter` | `.straymark/charters/`（声明式 `NN-slug.md` + 遥测 `NN-slug.telemetry.yaml`） | 通过 `charter new` 搭建脚手架；操作者拥有 trigger 与生命周期的转换 | + +> 参见 `STRAYMARK.md` 第 15 节及 `.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md`，了解粒度启发式、生命周期与 SpecKit ↔ Charter 桥接。 + +--- + +## 何时编写文档 + +| 场景 | 操作 | +|------|------| +| 复杂代码（`straymark analyze`；回退条件：>20 行） | AILOG | +| 多个备选方案间的决策 | AIDEC | +| 认证/授权/PII 变更 | AILOG + `risk_level: high` + ETH | +| 公共 API 或数据库模式变更 | AILOG + 考虑 ADR | +| 机器学习模型/提示词变更 | AILOG + 人工审核 | +| 安全关键依赖变更 | AILOG + 人工审核 | +| OTel 埋点变更 | AILOG + 标签 `observabilidad` | +| 跨多个会话的实施块（>1 天，跨多个阶段 >5 个任务） | 声明一个 **Charter**（`straymark charter new`） | +| 横向技术债务（先前 Charter 的遗留、横跨多个模块、需要专用 Charter、需要人工优先级） | **TDE** —— 与单 Charter 的 `R` 不同；参见 AGENT-RULES.md §3 | + +**不要记录**：凭据、令牌、PII、机密信息。 + +--- + +## 最低元数据 + +```yaml +--- +id: AILOG-2026-03-25-001 +title: Brief description +status: accepted +created: 2026-03-25 +agent: agent-name-v1.0 +confidence: high | medium | low +review_required: true | false +risk_level: low | medium | high | critical +# 可选法规字段（按上下文启用）： +# eu_ai_act_risk: not_applicable +# nist_genai_risks: [] +# iso_42001_clause: [] +# observability_scope: none +--- +``` + +--- + +## 需要人工审核 + +在以下情况下标记 `review_required: true`： + +- `confidence: low` +- `risk_level: high | critical` +- 安全决策 +- 不可逆变更 +- 机器学习模型或提示词变更 +- 安全关键依赖变更 +- 文档类型：ETH、ADR、REQ、SEC、MCARD、DPIA + +--- + +## 目录结构 + +``` +.straymark/ +├── 00-governance/ ← 策略，AI-GOVERNANCE-POLICY.md +├── 01-requirements/ ← REQ +├── 02-design/decisions/ ← ADR +├── 03-implementation/ ← 指南 +├── 04-testing/ ← TES +├── 05-operations/incidents/ ← INC +├── 06-evolution/technical-debt/ ← TDE +├── 07-ai-audit/ +│ ├── agent-logs/ ← AILOG +│ ├── decisions/ ← AIDEC +│ └── ethical-reviews/ ← ETH, DPIA +├── 08-security/ ← SEC +├── 09-ai-models/ ← MCARD +├── charters/ ← Charter（NN-slug.md + NN-slug.telemetry.yaml） +└── templates/ ← 模板（包括 charter/ 子目录） +``` + +--- + +## 工作流 + +``` +1. 评估 → 这是否需要文档记录？ + ↓ +2. 加载 → 对应的模板 + ↓ +3. 创建 → 使用正确的命名约定 + ↓ +4. 标记 → 如适用则标记 review_required +``` + +--- + +## 级别 + +### 置信度 +| 级别 | 操作 | +|------|------| +| `high` | 继续执行 | +| `medium` | 记录替代方案 | +| `low` | `review_required: true` | + +### 风险 +| 级别 | 示例 | +|------|------| +| `low` | 文档、格式 | +| `medium` | 新功能 | +| `high` | 安全、API | +| `critical` | 生产环境、不可逆 | + +--- + +## 法规对齐 + +| 标准 | 关键文档 | +|------|----------| +| ISO/IEC 42001:2023 | AI-GOVERNANCE-POLICY.md（核心） | +| EU AI Act | ETH（风险分类）、INC（事件报告） | +| NIST AI RMF / 600-1 | ETH（12 个 GenAI 风险类别）、AILOG | +| GDPR | ETH（数据隐私）、DPIA | +| ISO/IEC 25010:2023 | REQ（质量）、ADR（质量影响） | +| OpenTelemetry | 可选 — 参见 OBSERVABILITY-GUIDE | +| C4 Model | ADR 图表 — 参见 C4-DIAGRAM-GUIDE | + +--- + +## 技能（Claude Code） + +| 命令 | 用途 | +|------|------| +| `/straymark-status` | 检查文档状态和合规性 | +| `/straymark-new` | 创建任意类型文档（交互式） | +| `/straymark-ailog` / `/straymark-aidec` / `/straymark-adr` | AILOG / AIDEC / ADR 的快速快捷方式 | +| `/straymark-mcard` / `/straymark-sec` | Model Card / SEC 评估的交互流程 | +| `/straymark-charter-new` | 搭建一个 Charter（声明式事前工作单元） | +| `/straymark-audit-prompt CHARTER-XX` *(fw-4.9.0+，在 fw-4.9.0 中重构)* | 外部多模型审计 — 在规范路径写入统一 prompt | +| `/straymark-audit-execute [CHARTER-XX]` *(fw-4.9.0+)* | 在审计员 CLI 中运行 — 读取 prompt，使用 tool use 审计，写入 report | +| `/straymark-audit-review CHARTER-XX` *(fw-4.9.0+，在 fw-4.9.0 中扩展)* | 合并 N 个 reports 为 review.md（6 节）+ YAML 合并入遥测 | + +--- + +## 模式 + +| 模式 | 文档 | +|------|------| +| Follow-ups backlog(中央注册表 + drift 检测) *(fw-4.10.0+)* | [FOLLOW-UPS-BACKLOG-PATTERN.md](FOLLOW-UPS-BACKLOG-PATTERN.md) | + +--- + +*StrayMark fw-4.17.0 | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/00-governance/i18n/zh-CN/SPECKIT-CHARTER-BRIDGE.md b/.straymark/00-governance/i18n/zh-CN/SPECKIT-CHARTER-BRIDGE.md new file mode 100644 index 0000000..21ce60c --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/SPECKIT-CHARTER-BRIDGE.md @@ -0,0 +1,243 @@ +# SpecKit ↔ StrayMark Charter 桥接 + +> **状态**：经验性模式（`v0`）。需在第二个领域中验证后才会结晶（原则 #12）。如有新用例，通过 PR 进行细化。 + +## 本文档解决的问题 + +[SpecKit](https://github.com/StrangeDaysTech/speckit) 为一个 feature 提供 `spec.md`、`plan.md` 与 `tasks.md`。StrayMark 提供 Charter、AILOG、AIDEC、ADR。**没有任何权威文档解释一个 SpecKit feature 何时应产出一个 Charter、应使用何种粒度、由谁触发创建、何时创建。** 这正是 [issue #113](https://github.com/StrangeDaysTech/straymark/issues/113) 所报告的核心议题——一个让 Agent（Claude、Gemini、Copilot）形成二元心智模型（`SpecKit = 规划，StrayMark = 审计轨迹`）、并悄然丢弃第三层（即"工作-作为-可审计-可发布单元"，Charter 所在的层）的发现性缺口。 + +本文件就是答案。 + +## 心智模型 + +三层结构，含交接点： + +| 层级 | 居于 | 目的 | 所有者 | +|------|------|------|--------| +| **1. 规范** | `specs/NNN-feature/{spec,plan,tasks,research,quickstart}.md` | feature 是什么、为什么存在、技术层面将如何实施。SpecKit 通过 `/speckit-specify` → `/speckit-plan` → `/speckit-tasks` 产出。 | 操作者（含 Agent 协助）。 | +| **2. 有界执行单元** | `.straymark/charters/NN-slug.md` | 一次可发布切片的合约。将事前范围（文件、风险、任务子集）与事后遥测（drift、audit、教训）配对。 | 操作者声明 Charter；Agent 在其内执行。 | +| **3. 实施轨迹** | `.straymark/07-ai-audit/agent-logs/AILOG-*.md`（以及视情况而定的 AIDEC、ADR） | 实际工作内容、原因与置信度的逐日记录。每个 AILOG 通过 `originating_charter:` 引用 Charter（或 Charter 通过 `originating_ailogs:` 聚合 AILOG）。 | Agent 在工作时创建；操作者审核。 | + +**桥接就是 Charter。** 规范层级太高，不利于 drift 检查（"你交付了规范吗？"在有用的时间窗内无法回答）；AILOG 层级太低，不利于以其为单位发布（"你交付了这个 AILOG 吗？"是错误的单位）。Charter 处于恰当的粒度：你可以在数日内（而非数月内）做审计的稳定范围合约。 + +## SpecKit feature 何时产出 Charter？ + +当**任一**条件成立时，一个 SpecKit feature 应至少产出一个 Charter： + +1. feature 的 `tasks.md` 包含 **5 个或更多任务**，无法在单一会话中完成。 +2. feature 横跨 **2 个或更多 SpecKit 阶段**（Setup、Foundation、User Stories、Polish 等），且你打算将其作为一个单元一起发布。 +3. 工作在完成时值得**外部审计**（跨模型审查、跨团队审查）。 +4. 你希望在关闭时获得**可度量的遥测**（effort estimate vs. 实际、drift 数量、教训）。 + +**不应**产出 Charter 当： + +- feature 足够小，可在一次会话内完成（<1 天，<5 个任务）。仅使用 AILOG——Charter 的开销超过其可审计性所带来的收益。 +- feature **仅为规划**（尚无代码）。等到 `tasks.md` 存在再说；Charter 合约需要列出具体任务。 +- feature 是**没有计划范围的维护**（例如"按需修 bug"）。对于即兴维护，AILOG 已足够。 + +## 粒度启发式 + +当一个 feature 值得使用 Charter，按**可发布单元**而非按结构单元选择粒度。具体而言： + +### 启发式 1 — 每一可发布切片对应一个 Charter + +如果 feature 有阶段（如 SpecKit 典型的 Foundation → US1 → US2 → US3 → Polish），**第一个 Charter 包裹基础切片**（一起作为 `v0.1` 发布的所有内容）。后续 Charter 包裹后续切片。Effort estimate **M** 是可发布切片的中位桶；**L** 用于完整 feature 的切片。 + +``` +specs/001-peek-mvp-foundation/ +├── spec.md +├── plan.md +└── tasks.md → CHARTER-01 (Foundation: T001-T012, effort M) + CHARTER-02 (peek MVP: T013-T044, effort L) +``` + +### 启发式 2 — 不要按 User Story 划分 + +User Story 太细。一个 2-3 个任务的 US 应位于 Charter *内部*，而不是其自己的 Charter。每 US 的遥测是噪音；每可发布切片的遥测是信号。 + +### 启发式 3 — 不要按 feature 划分 + +一个分两次切片发布的 feature（如 MVP → polish）应有两个 Charter，而不是一个。可做 drift 检查的 Charter 合约是"这个切片发布了什么"，而非"我们最终建造了什么"。 + +### 启发式 4 — 边界情况：≥10 个任务跨 4+ 阶段 + +当一个 feature 异常庞大时，第三个 Charter（或将基础切片再拆分为"scaffolding" + "core"）可能是合理的。以 effort estimate **L** 作为上限；如果你估计为 **XL**，那是一个信号——这个 feature 应被重新规范化。 + +## 创建时机 + +``` +/speckit-specify → spec.md +/speckit-plan → plan.md +/speckit-tasks → tasks.md + ↓ + ┌────────────────────────────────────────┐ + │ ★ Charter 声明点 ★ │ + │ │ + │ 操作者运行 `straymark charter new` │ + │ --from-spec specs/NNN-feature/spec.md│ + │ --type │ + │ │ + │ Charter 状态：declared │ + │ → 操作者填写 scope、files、tasks │ + │ → 执行时改为 status: in-progress │ + └────────────────────────────────────────┘ + ↓ +/speckit-implement → 任务被执行 + → AILOG 被创建（`originating_charter:` → Charter） + ↓ +straymark charter drift CHARTER-NN → 文件 vs commit 检查 +straymark charter audit CHARTER-NN → 外部审计（可选） +straymark charter close CHARTER-NN → 遥测，状态：closed +``` + +**关键不变量**：在 `/speckit-implement` 启动**之前**声明 Charter。Charter 是一份合约；在执行之后才声明会让 drift 检查失去意义。 + +## frontmatter 关联 + +Charter 的 frontmatter 显式引用 SpecKit feature： + +```yaml +charter_id: CHARTER-01-workspace-foundation +status: declared +effort_estimate: M +trigger: tasks.md 在 2 个阶段内有 12 个有序任务；作为 v0.1 发布。 +originating_spec: specs/001-peek-mvp-foundation/spec.md +``` + +反向（spec → Charter）依靠惯例——如果你的 `plan.md` 模板有 "Phase 5: Implementation Tracking" 章节，就在那里列出当前活动的 Charter。SpecKit 目前没有为此提供 schema 槽位；这是新兴的惯例。 + +执行期间创建的 AILOG 应引用该 Charter： + +```yaml +id: AILOG-2026-05-08-005 +title: T013, T016-T026 — US1 P1 MVP core + TUI + peek bin +agent: claude-code-v4.7 +confidence: high +risk_level: medium +review_required: false +originating_charter: CHARTER-02-peek-mvp-foundation +``` + +## 生命周期映射 + +| SpecKit 阶段 | Charter 事件 | StrayMark CLI | +|-------------|-------------|---------------| +| `/speckit-tasks` 完成 | **声明 Charter** | Skill `/straymark-charter-new` 或 `straymark charter new --from-spec …` | +| 第一个任务开始 | 操作者把 `declared` 翻为 `in-progress` | （手动编辑 frontmatter） | +| 每个任务执行 | 产出 AILOG（当 STRAYMARK.md §6 要求时） | `/straymark-ailog` | +| 遇到主要决策 | 产出 AIDEC | `/straymark-aidec` | +| 架构变化 | 产出 ADR | `/straymark-adr` | +| 最后一个任务完成，关闭前 | Drift 检查 | `straymark charter drift CHARTER-NN` | +| 可选外部审查 | 多模型审计 | `straymark charter audit CHARTER-NN` + `/straymark-audit-prompt` + `/straymark-audit-execute` + `/straymark-audit-review` | +| 切片已发布 | 关闭 Charter | `straymark charter close CHARTER-NN`（状态：`closed`，发出 telemetry yaml） | + +## 多 Charter 执行期间的 spec 维护 + +> **经验锚点**：由 [issue #150](https://github.com/StrangeDaysTech/straymark/issues/150) 浮现——Sentinel 让单个 `specs/002-commshub/plan.md`（2026-04-21 提交）连续驱动了**七个 Charter**（CHARTER-07 至 CHARTER-17，约 1 个月）。十二条经验性发现实质上影响着下一个 Charter 的 scope，但 plan 中**并未**反映这些。下面的模式编纂了 Sentinel 在填写 CHARTER-18 之前发现的内容。 + +上方的生命周期映射假设**一次性**：SpecKit 工件生成一次，然后声明并执行 Charter。这种方式对于产出单个 Charter 的 feature 是 OK 的。当单个 spec 在几周时间内驱动多个 Charter 时，**规划工件相对于已发布代码会发生漂移**——而盲目重新运行 `/speckit-plan` 更糟：再生会断言已发布 user story 的事项，而真实代码并不实现这些；未来的读者（审计员、agents、新操作者）会信任这些再生工件为 ground truth。 + +本节回答**如何**，而非**是否**：什么样的纪律能够使 spec 在多 Charter 执行期间与代码保持同步，**而不让**再生步骤对已经发布的部分撒谎。 + +### 何时刷新 + +下述条件**任一**满足时，spec 刷新是合理的： + +1. **同一 spec 下已关闭 ≥3 个 Charter**——未反映的执行细节量已经足够大，下一个 Charter 的 scope 决策有继承陈旧前提的风险。 +2. **距离上次刷新（或初次生成）≥4 个日历周**，且窗口内已关闭 ≥2 个 Charter。 +3. **跨已关闭 Charter 累计的 AILOG `## Risk: R(new, not in Charter)` 数量超过 ~6**——spec 对风险的预期可量化地低估了实际领域。 +4. **下一个 Charter 的 user story 涉及前序 Charter 已经凭经验细化的基础设施**（新建表/migrations、抽出的 helper、固化的契约），而 spec 描述的是细化前状态。 + +如果都不满足，且下一个 Charter 指向前序 Charter 未触及的新子系统，**跳过刷新**。Spec 的稳定性本身有价值；每个 Charter 都刷新会产生 churn，却缺乏对应的清晰度收益。 + +### 如何刷新：scope-limited prompt + +**不要**以空白板的方式重新运行 `/speckit-plan`。再生的 `plan.md` + `research.md` + `data-model.md` + `contracts/` + `quickstart.md` 会断言已发布 user story 的事项，而真实代码并不实现这些。 + +相反，使用 **scope-limited prompt** 调用 `/speckit-plan`： + +1. **显式命名目标阶段**（例如，"只刷新 US5 的规划——failover + tracking"）。 +2. **列出不可改动的锁定 sections**（例如，"Foundation、US1、US2、US3、US4 sections 不可变——已发布的代码是 ground truth，而非 plan"）。 +3. **引用记录精化过程的 AILOG**（例如，"参考 AILOG-2026-05-11-043 §R5 中的 `processed_events` 复用模式；在刷新的 data model 中反映这一点"）。 +4. **禁止再生 `tasks.md`**——见下一小节。 + +输出是 `plan.md`（可能还有 `research.md` / `data-model.md` / `contracts/`），其中目标阶段内容是新鲜的，锁定 sections 承载向前的是真正发布的状态，而非原本的愿景状态。 + +### 刷新后的三个机械门 + +在合并 spec-refresh PR 之前，依序执行三个 gate： + +**Gate (a) ——对照代码现实的验证。** +对 `data-model.md` 中每个非目标阶段实体，与实际 `db/migrations/*.sql`（或等价的 schema 来源）对 diff。对 `contracts/*.md` 中每个非目标阶段端点，与实际 handler 签名对 diff。锁定 section 中的任何分歧都会阻塞合并——那是再生在撒谎。Adopter 可以针对自己的 stack 编写脚本；CLI helper（`straymark spec-drift`）在路线图上（见 #150 Ask 3）。 + +**Gate (b) ——按 hunk 粒度审阅 diff。** +运行 `git diff specs/NNN-feature/`，按文件按 hunk 审阅。锁定 sections 的任何变更未经 PR 中显式的理由注释不可接受。在 scope-limited 时 diff 足够小，一坐就能完成。 + +**Gate (c) ——两 PR 拆分。** +将 spec-refresh 作为独立的 PR 落地。**对照代码**而非对照 plan-only 输出来审阅它。然后在*单独*的 PR 中针对刷新后的 spec 填写目标 Charter。把两者混在一起会折叠审阅表面：审阅者再也无法分辨某个 hunk 反映的是新发布的状态还是新规划的状态。 + +### 为什么**不要**在 spec 执行中途重新运行 `/speckit-tasks` + +`tasks.md` 文件在执行期间积累了实现追溯状态：已完成任务的 `[X]` 复选框、引用某个 Charter 发布了某个任务的 `*CHARTER-NN: *` 标注，可能还有带理由的 `^skipped` 标记。**再生 `tasks.md` 会摧毁这一状态。** 文件会变成一份没有任何已发布记录的新鲜任务清单。 + +纪律：在 spec 处于多 Charter 执行中途时，**绝不**重新运行 `/speckit-tasks`。相反，**只针对目标阶段手工编辑 `tasks.md`**——为刷新后的 scope 追加新任务，让已发布的 sections（`[X]` + `*CHARTER-NN:*` 注释）保持不动。 + +如果你发现原本的 `tasks.md` 在已发布 sections 中存在错误（例如，某个任务被错误标为 `[X]`，但其工作实际上跨两个 Charter），用 Git commit 手工修正。把 `tasks.md` 当作从首次执行起的历史记录；它不再是可再生的工件。 + +### Constitution Check 再评估的节奏 + +SpecKit 的 Constitution Check 通常在 `/speckit-plan` 时只运行一次。在针对同一 spec 的多 Charter 执行中，*何时*再评估的问题是隐式的。为了把这一点显式化： + +- **每 Charter（推荐）**——在针对该 spec 声明的每个新 Charter 起始时再评估 Constitution Check。该 check 成本低（读取宪法；对照 Charter 声明的 scope），在执行 commit 之前就能尽早抓住 drift。 +- **每次 spec 刷新（刷新发生时强制）**——当 scope-limited 的 `/speckit-plan` 刷新落地时，refresh PR 必须针对刷新后的 plan 重新运行 Constitution Check。如果框架版本已经移动（例如 `fw-4.10.x → fw-4.14.x`），Constitution Check 可能由于存在新的 gate 而给出不同结果。 +- **单独的 framework 升级不触发**——Charters 之间的 `straymark update-framework` **不**要求在 spec 未关闭的情况下立即再运行 Constitution Check。该 check 应用于下一次自然边界（下一个 Charter 声明或 spec 刷新）。 + +将此编码为显式节奏（而非"谁想就谁决定"）闭合了 Sentinel 在 CHARTER-17 后报告的一处反复出现的模糊性。 + +### 路线图：`straymark spec-drift` + +与 `straymark charter drift` 类似的 CLI 命令，但在 spec 粒度上工作——解析 `data-model.md` → 实体 → 与 `db/migrations/*.sql` 对 diff；解析 `contracts/*.md` → 端点 → 与 handler 签名对 diff。它会机械化上方的 Gate (a)。 + +刻意推迟到发布后的一个 Charter（独立跟踪）。CLI 表面只对其 spec 格式遵循 SpecKit 约定的 adopter 有意义；语言检测层（Go vs Rust vs TypeScript vs Python handler；SQL vs ORM 定义的 schema）非平凡，且应当由真实 adopter stack 提供信息后再走自己的设计周期。上方的纪律（手工执行 Gates a/b/c）是 v0；CLI 是机械化最昂贵 gate 的 v1。 + +## 反模式 + +**不要"以防万一"开 Charter。** 没有清晰可发布切片的 Charter 会变成愿望清单。操作者最终会把它关为 `closed: aborted`，遥测毫无意义。 + +**不要按 User Story 开 Charter。** 每 US 的遥测过于嘈杂，无法指导未来的估算。要聚合。 + +**不要省略 `originating_spec` 字段。** 即便 Charter 包裹的工作没有 SpecKit spec，也要改为设置 `originating_ailogs:`。无来源的 Charter 是反模式（暗示动机未被记录）。 + +**没有就绪的审计员 CLI 时，不要运行 `straymark charter audit`。** 审计仅为编排——`straymark` 不调用 LLM API。如果没有 N 个审计员 CLI 就绪，跳过该步骤；不进行外部审计直接关闭 Charter。 + +**不要在 drift 检查 + telemetry yaml 之前把状态改为 `closed`。** `straymark charter close` 原子化地完成两者；手动关闭跳过了不变量。 + +**不要在 spec 执行中途重新运行 `/speckit-tasks`。** 再生 `tasks.md` 会摧毁形成历史轨迹的 `[X]` 完成标记与 `*CHARTER-NN:* …` 标注。安全路径见上方"多 Charter 执行期间的 spec 维护"章节（仅针对目标阶段手工编辑）。 + +## 此模式不适用的场景 + +此桥接假设的是 SpecKit 驱动的 feature 流程，包含多任务、多会话的实施。它不适用于： + +- **单会话 feature** — 仅使用 AILOG。 +- **仅架构、无实施的工作**（如"设计下一代 schema"）— 使用 ADR。 +- **没有新行为的纯重构** — 使用 AILOG + 标记 `refactor:`。 +- **事故响应与 hotfix** — 使用 INC + AILOG。 +- **仅合规交付物**（如季度 DPIA 刷新）— 直接使用相关文档类型。 + +如果你的工作属于上述任一类，*不要声明 Charter*。当没有可发布切片需要包裹时，Charter 的成本超过其价值。 + +## 另请参阅 + +- [`EMERGENT-OBSERVATION-DESIGN.md`](EMERGENT-OBSERVATION-DESIGN.md) —— 元模式，解释*为什么*此桥接中的多源链接在多 Charter 执行期间产生涌现观察。 +- `STRAYMARK.md` §6（何时编写文档）与 §15（Charter 作为有界工作单元） +- `.straymark/templates/charter/charter-template.md` — 声明式模板 +- `.straymark/templates/charter/charter-telemetry-template.yaml` — 遥测模板 +- `.straymark/schemas/charter.schema.v0.json` — 声明式 frontmatter 的 JSON Schema +- `.straymark/schemas/charter-telemetry.schema.v0.json` — 遥测的 JSON Schema +- `.claude/skills/straymark-charter-new/SKILL.md`（以及 Gemini / 通用等价物） + +> **被引用的经验性背景**（issue #113）：一个全新的 Rust CLI/TUI 套件，Claude Opus 4.7 通过权威入口点（`STRAYMARK.md`、项目宪章、`CLAUDE.md` 检查清单、可用的 `/straymark-*` skills、`/straymark-status`）入门。Charter *最终*被采用（2 个 Charter：foundation + MVP），但只在用户明确提示之后——这证实了缺口是系统性的，而非会话特有的。本文档消除了该缺口。 + +--- + +*语言*：[English](../../SPECKIT-CHARTER-BRIDGE.md) | [Español](../es/SPECKIT-CHARTER-BRIDGE.md) | 简体中文 diff --git a/.straymark/00-governance/i18n/zh-CN/TC260-IMPLEMENTATION-GUIDE.md b/.straymark/00-governance/i18n/zh-CN/TC260-IMPLEMENTATION-GUIDE.md new file mode 100644 index 0000000..d002351 --- /dev/null +++ b/.straymark/00-governance/i18n/zh-CN/TC260-IMPLEMENTATION-GUIDE.md @@ -0,0 +1,119 @@ +# TC260 实施指南 — StrayMark + +> 根据 **AI 安全治理框架 v2.0**(TC260,2025-09-15)填写 TC260RA 文档的实务指南。 + +**Languages**: [English](../../TC260-IMPLEMENTATION-GUIDE.md) | [Español](../es/TC260-IMPLEMENTATION-GUIDE.md) | 简体中文 + +--- + +## 何时创建 TC260RA + +当 `regional_scope` 包含 `china` 且符合以下任一情况时,创建 TC260 风险评估: + +- 您部署或修改的系统是或包含 AI 模型。 +- 应用面向中国大陆用户,或运营者在中国大陆注册。 +- 系统涉及触及中国大陆的跨境数据流。 +- 预期发生新的模型版本、场景或规模跃升。 + +TC260RA 与 ETH 上的 EU AI Act 风险分类互补,通过相关 ETH / MCARD / AILOG 上的 `related: [TC260RA-...]` 引用。 + +--- + +## 三标准 + +TC260 v2.0 在三个正交维度上分级风险,然后组合为单一等级(low / medium / high / very_high / extremely_severe)。 + +### 1. 应用场景(`tc260_application_scenario`) + +| 场景 | 例子 | 固有风险底线 | +|------|------|-----------| +| `public_service` | 政府聊天机器人、公共信息门户 | medium | +| `healthcare` | 临床决策支持、医学影像 | high | +| `finance` | 信贷评分、KYC、欺诈检测 | high | +| `safety_critical` | 自动驾驶、工业控制、能源 | very_high | +| `content_generation` | 文本/图像/视频合成 | medium | +| `social` | 推荐、排序、社交 | medium | +| `industrial_control` | OT 系统、机器人 | very_high | +| `other` | 简要记录 | — | + +### 2. 智能等级(`tc260_intelligence_level`) + +| 等级 | 定义 | +|------|------| +| `narrow` | 单一用途、确定性输出 | +| `foundation` | 通用基础模型(LLM、视觉语言),无工具使用 | +| `agentic` | 基础模型 + 自主工具使用,可在现实世界采取行动 | +| `general` | 接近通用人工智能 — 跨域广泛能力 | + +### 3. 应用规模(`tc260_application_scale`) + +| 规模 | 定义 | +|------|------| +| `individual` | 单一用户 / 小团队 | +| `organization` | 单一组织或企业 | +| `societal` | 公众的相当部分(≥ 100 万用户) | +| `cross_border` | 跨中国大陆与其他司法辖区运营 | + +--- + +## 综合等级 + +无公开的数字公式。使用以下矩阵作为起点并记录推理: + +| 场景 \ 智能 | Narrow | Foundation | Agentic | General | +|-------------|--------|-----------|---------|---------| +| public_service | low → medium | medium | high | very_high | +| healthcare / finance | medium | high | high | very_high | +| safety_critical | high | very_high | very_high | extremely_severe | +| content_generation | low | medium | high | very_high | +| social | low | medium | high | very_high | +| industrial_control | high | very_high | very_high | extremely_severe | + +**规模修饰**: +- `individual`、`organization` → 不变。 +- `societal` → 上调一级。 +- `cross_border` → 上调一级 **并** 要求显式跨境数据分析(参见 PIPL-PIPIA-GUIDE)。 + +--- + +## 风险分类:如何填充 + +### 内生(`tc260_endogenous_risks`) + +模型固有:`hallucination`、`bias`、`robustness`、`data_leakage`、`prompt_injection`、`model_extraction`。 + +### 应用(`tc260_application_risks`) + +技术使用引发:`misuse`、`scope_creep`、`dependency`、`availability`、`integration_flaw`。 + +### 衍生(`tc260_derivative_risks`) + +二阶社会影响:`labor_displacement`、`opinion_shaping`、`ecosystem_disruption`、`monoculture`、`loss_of_skill`。 + +对于 `very_high` 与 `extremely_severe` 等级,v2.0 明确要求 **灾难性风险监测**:在 TC260RA 第 5 节(治理措施)中记录。 + +--- + +## 从其他文档关联 + +当非 TC260RA 文档设置 `tc260_risk_level: high`(或更高)时,验证规则 **CROSS-004** 要求 `review_required: true`。TC260RA 自身应通过 `related:` 关联: + +```yaml +related: + - TC260RA-2026-04-25-001 + - MCARD-2026-04-25-001 + - PIPIA-2026-04-25-001 +``` + +--- + +## 复审周期 + +| 触发 | 行动 | +|------|------| +| 模型版本变更 | 重新执行第 4 节(技术应对) | +| 场景扩展 | 重新分级:场景 × 智能 × 规模 | +| 跨越规模阈值(如 100 万用户) | 等级评估 | +| TC260 法规更新 | 完整重审 | + + diff --git a/.devtrail/01-requirements/.gitkeep b/.straymark/01-requirements/.gitkeep similarity index 100% rename from .devtrail/01-requirements/.gitkeep rename to .straymark/01-requirements/.gitkeep diff --git a/.devtrail/02-design/decisions/.gitkeep b/.straymark/02-design/decisions/.gitkeep similarity index 100% rename from .devtrail/02-design/decisions/.gitkeep rename to .straymark/02-design/decisions/.gitkeep diff --git a/.devtrail/03-implementation/.gitkeep b/.straymark/03-implementation/.gitkeep similarity index 100% rename from .devtrail/03-implementation/.gitkeep rename to .straymark/03-implementation/.gitkeep diff --git a/.devtrail/03-implementation/NIST-AI-600-1-GENAI-RISKS.md b/.straymark/03-implementation/NIST-AI-600-1-GENAI-RISKS.md similarity index 95% rename from .devtrail/03-implementation/NIST-AI-600-1-GENAI-RISKS.md rename to .straymark/03-implementation/NIST-AI-600-1-GENAI-RISKS.md index 58f8d03..dafb835 100644 --- a/.devtrail/03-implementation/NIST-AI-600-1-GENAI-RISKS.md +++ b/.straymark/03-implementation/NIST-AI-600-1-GENAI-RISKS.md @@ -2,7 +2,7 @@ > **Standard**: NIST AI 600-1 --- Artificial Intelligence Risk Management Framework: Generative AI Profile > -> NIST AI 600-1 defines 12 risk categories specific to generative AI systems. This reference maps each category to DevTrail templates, frontmatter values, and practical mitigations. Use it alongside the NIST AI RMF function guides to ensure comprehensive GenAI risk coverage. +> NIST AI 600-1 defines 12 risk categories specific to generative AI systems. This reference maps each category to StrayMark templates, frontmatter values, and practical mitigations. Use it alongside the NIST AI RMF function guides to ensure comprehensive GenAI risk coverage. --- @@ -16,7 +16,7 @@ Generative AI systems may produce information that could assist in the creation, - A code generation model produces functional exploit code targeting critical infrastructure control systems - An AI assistant responds to queries about biological agent cultivation with actionable detail -### DevTrail Mapping +### StrayMark Mapping | Aspect | Value | |--------|-------| @@ -43,7 +43,7 @@ Generative AI systems may produce outputs that are factually incorrect, fabricat - A code generation model invents API methods that are not part of the referenced library - A conversational AI provides medical information that contradicts established clinical guidelines -### DevTrail Mapping +### StrayMark Mapping | Aspect | Value | |--------|-------| @@ -70,7 +70,7 @@ Generative AI systems may generate content that promotes, glorifies, or provides - An image generation model creates realistic depictions of graphic violence on request - A chatbot provides detailed instructions for self-harm when prompted by a vulnerable user -### DevTrail Mapping +### StrayMark Mapping | Aspect | Value | |--------|-------| @@ -97,7 +97,7 @@ Generative AI systems may memorize, leak, or inadvertently reveal personal data, - A conversational AI retains and surfaces information from one user's session to another - A model trained on proprietary data leaks trade secrets through carefully crafted prompts -### DevTrail Mapping +### StrayMark Mapping | Aspect | Value | |--------|-------| @@ -124,7 +124,7 @@ The training, fine-tuning, and inference of generative AI models consume substan - Frequent retraining cycles multiply the environmental cost without proportional capability gains - Deploying inference at scale generates sustained energy consumption across data center infrastructure -### DevTrail Mapping +### StrayMark Mapping | Aspect | Value | |--------|-------| @@ -151,7 +151,7 @@ Generative AI systems may amplify societal biases present in training data, prod - A text model associates negative stereotypes with specific nationalities or genders - Widespread use of a single AI writing assistant homogenizes communication styles across an industry -### DevTrail Mapping +### StrayMark Mapping | Aspect | Value | |--------|-------| @@ -178,7 +178,7 @@ Risks arising from inappropriate levels of human oversight, overreliance on AI o - A system is deployed without clear escalation paths for cases where human judgment is needed - Users develop excessive trust in AI outputs after prolonged interaction without encountering errors -### DevTrail Mapping +### StrayMark Mapping | Aspect | Value | |--------|-------| @@ -205,7 +205,7 @@ Generative AI can be used to create or amplify misinformation, disinformation, a - AI-generated deepfake media is used to impersonate public figures for disinformation campaigns - Automated content generation floods information channels with low-quality, misleading content at scale -### DevTrail Mapping +### StrayMark Mapping | Aspect | Value | |--------|-------| @@ -232,7 +232,7 @@ Generative AI systems introduce novel attack surfaces including prompt injection - A model is manipulated through adversarial inputs to produce outputs that bypass content filters - Training data poisoning causes a model to produce subtly incorrect outputs in specific domains -### DevTrail Mapping +### StrayMark Mapping | Aspect | Value | |--------|-------| @@ -259,7 +259,7 @@ Generative AI may infringe on intellectual property rights by reproducing copyri - An image generation model produces outputs that closely replicate the distinctive style of a living artist - A model trained on proprietary corporate documents generates outputs that reveal protected trade secrets -### DevTrail Mapping +### StrayMark Mapping | Aspect | Value | |--------|-------| @@ -286,7 +286,7 @@ Generative AI systems may produce sexually explicit, obscene, or degrading conte - A text model generates degrading descriptions of individuals based on their demographic characteristics - An AI system produces non-consensual intimate imagery by combining publicly available photographs with generative techniques -### DevTrail Mapping +### StrayMark Mapping | Aspect | Value | |--------|-------| @@ -313,7 +313,7 @@ Risks arising from the integration of third-party AI components, models, dataset - An API provider changes model behavior without notice, breaking assumptions in dependent systems - A fine-tuned model inherits undisclosed vulnerabilities from its base model -### DevTrail Mapping +### StrayMark Mapping | Aspect | Value | |--------|-------| @@ -330,9 +330,9 @@ Risks arising from the integration of third-party AI components, models, dataset --- -## Summary: GenAI Risk Categories to DevTrail Mapping +## Summary: GenAI Risk Categories to StrayMark Mapping -| Category | Identifier | Primary DevTrail Template | Frontmatter Value | +| Category | Identifier | Primary StrayMark Template | Frontmatter Value | |----------|-----------|---------------------------|-------------------| | CBRN Information | `cbrn` | ETH | `nist_genai_risks: [cbrn]` | | Confabulation | `confabulation` | ETH | `nist_genai_risks: [confabulation]` | @@ -349,6 +349,6 @@ Risks arising from the integration of third-party AI components, models, dataset --- -*NIST AI 600-1 Generative AI Risk Categories Reference --- DevTrail Framework* +*NIST AI 600-1 Generative AI Risk Categories Reference --- StrayMark Framework* - + diff --git a/.devtrail/03-implementation/NIST-AI-RMF-GOVERN-GUIDE.md b/.straymark/03-implementation/NIST-AI-RMF-GOVERN-GUIDE.md similarity index 91% rename from .devtrail/03-implementation/NIST-AI-RMF-GOVERN-GUIDE.md rename to .straymark/03-implementation/NIST-AI-RMF-GOVERN-GUIDE.md index 52233e2..02d4be6 100644 --- a/.devtrail/03-implementation/NIST-AI-RMF-GOVERN-GUIDE.md +++ b/.straymark/03-implementation/NIST-AI-RMF-GOVERN-GUIDE.md @@ -13,9 +13,9 @@ Establish, document, and communicate organizational policies that define expecta > Policies set the organizational baseline. Without explicit policies, teams default to inconsistent individual judgment. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | AI governance policy | AI-GOVERNANCE-POLICY.md | Full document | | Documentation standards | DOCUMENTATION-POLICY.md | Full document | @@ -38,9 +38,9 @@ Define clear roles, responsibilities, and accountability structures for AI risk > Accountability without assignment is an illusion. Every risk management activity needs a named responsible party. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Roles and responsibilities | AI-GOVERNANCE-POLICY.md | Section 2.2 (Roles and Responsibilities) | | Agent autonomy boundaries | AGENT-RULES.md | Autonomy Table, Human Review Triggers | @@ -63,9 +63,9 @@ Ensure that AI development and governance teams include diverse perspectives. Di > Homogeneous teams produce homogeneous risk assessments. Diversity in perspective is a governance control, not just an HR objective. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Team composition guidance | AI-GOVERNANCE-POLICY.md | Section 4 (Support and Resources) | | Competency requirements | AI-GOVERNANCE-POLICY.md | Section 4.2 (Competencies) | @@ -87,9 +87,9 @@ Foster an organizational culture that values responsible AI development, encoura > Culture determines whether policies are followed in practice or exist only on paper. Governance is only as strong as the culture that sustains it. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Organizational principles | PRINCIPLES.md | Full document | | Ethical guidelines | PRINCIPLES.md | Core Principles section | @@ -111,9 +111,9 @@ Engage internal and external stakeholders regularly in AI governance activities. > Governance conducted in isolation lacks the external perspective needed to anticipate real-world impacts. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Management reviews | MANAGEMENT-REVIEW-TEMPLATE.md | Full document | | Stakeholder feedback | MANAGEMENT-REVIEW-TEMPLATE.md | Feedback Summary section | @@ -136,9 +136,9 @@ Govern the AI supply chain by maintaining transparency over third-party componen > You cannot manage what you cannot see. Supply chain governance starts with a complete and current inventory. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Component inventory | SBOM | Full document | | Third-party services | SBOM | Third-Party Services section | @@ -155,9 +155,9 @@ Govern the AI supply chain by maintaining transparency over third-party componen --- -## Summary: GOVERN Function to DevTrail Mapping +## Summary: GOVERN Function to StrayMark Mapping -| Category | Description | Primary DevTrail Document | Key Fields / Sections | +| Category | Description | Primary StrayMark Document | Key Fields / Sections | |----------|-------------|---------------------------|----------------------| | GV-1 | Policies | AI-GOVERNANCE-POLICY.md, DOCUMENTATION-POLICY.md | Full documents | | GV-2 | Accountability | AGENT-RULES.md, AI-GOVERNANCE-POLICY.md | Autonomy Table, Section 2.2 | @@ -168,6 +168,6 @@ Govern the AI supply chain by maintaining transparency over third-party componen --- -*NIST AI RMF GOVERN Function Implementation Guide --- DevTrail Framework* +*NIST AI RMF GOVERN Function Implementation Guide --- StrayMark Framework* - + diff --git a/.devtrail/03-implementation/NIST-AI-RMF-MANAGE-GUIDE.md b/.straymark/03-implementation/NIST-AI-RMF-MANAGE-GUIDE.md similarity index 89% rename from .devtrail/03-implementation/NIST-AI-RMF-MANAGE-GUIDE.md rename to .straymark/03-implementation/NIST-AI-RMF-MANAGE-GUIDE.md index c9af2ed..eebd877 100644 --- a/.devtrail/03-implementation/NIST-AI-RMF-MANAGE-GUIDE.md +++ b/.straymark/03-implementation/NIST-AI-RMF-MANAGE-GUIDE.md @@ -13,9 +13,9 @@ Plan and execute responses to identified risks. Risk responses include acceptanc > Every identified risk must have an explicit response strategy. Undocumented risk acceptance is implicit negligence. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Risk response decisions | ADR | Decision and Rationale section | | Recommended mitigations | ETH | Recommendations section | @@ -38,9 +38,9 @@ Implement specific technical and organizational controls to reduce risk severity > Mitigations must be verified, not assumed. Implement controls, test them, and document evidence of their effectiveness. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Security controls | SEC | Controls Implemented section | | Privacy mitigations | DPIA | Mitigation Measures section | @@ -63,9 +63,9 @@ Manage risks arising from third-party AI components, models, data sources, APIs, > Third-party components inherit and propagate risks. Organizations remain accountable for risks introduced by their suppliers. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Third-party inventory | SBOM | Third-Party Services, Components sections | | Component risk assessment | SBOM | Risk Assessment section | @@ -88,15 +88,15 @@ Monitor deployed AI systems for performance degradation, emerging risks, inciden > Deployment is not the end of risk management --- it is where real-world risks begin to manifest. Continuous monitoring is essential. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Incident tracking | INC | Full document | | Lifecycle status | AI-LIFECYCLE-TRACKER.md | Monitoring Phase section | | Operational monitoring | AILOG | Monitoring and observability entries | | Performance drift detection | TES | Regression and drift tests | -| System health | `devtrail status` | Documentation health metrics | +| System health | `straymark status` | Documentation health metrics | ### Implementation Checklist @@ -107,9 +107,9 @@ Monitor deployed AI systems for performance degradation, emerging risks, inciden --- -## Summary: MANAGE Function to DevTrail Mapping +## Summary: MANAGE Function to StrayMark Mapping -| Category | Description | Primary DevTrail Document | Key Fields / Sections | +| Category | Description | Primary StrayMark Document | Key Fields / Sections | |----------|-------------|---------------------------|----------------------| | MG-1 | Risk Response | ETH, ADR | Recommendations, Decision and Rationale | | MG-2 | Risk Mitigation | SEC, DPIA | Controls Implemented, Mitigation Measures | @@ -118,6 +118,6 @@ Monitor deployed AI systems for performance degradation, emerging risks, inciden --- -*NIST AI RMF MANAGE Function Implementation Guide --- DevTrail Framework* +*NIST AI RMF MANAGE Function Implementation Guide --- StrayMark Framework* - + diff --git a/.devtrail/03-implementation/NIST-AI-RMF-MAP-GUIDE.md b/.straymark/03-implementation/NIST-AI-RMF-MAP-GUIDE.md similarity index 89% rename from .devtrail/03-implementation/NIST-AI-RMF-MAP-GUIDE.md rename to .straymark/03-implementation/NIST-AI-RMF-MAP-GUIDE.md index b71d816..f894faa 100644 --- a/.devtrail/03-implementation/NIST-AI-RMF-MAP-GUIDE.md +++ b/.straymark/03-implementation/NIST-AI-RMF-MAP-GUIDE.md @@ -13,9 +13,9 @@ Document the AI system's purpose, operating environment, stakeholders, and inten > Establishing thorough context ensures that risk assessments are grounded in the system's actual deployment conditions rather than generic assumptions. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | System purpose and scope | AILOG | `title`, Summary section | | Operating environment | AILOG | Context section | @@ -38,9 +38,9 @@ Classify AI systems by risk level based on their intended use, potential for har > Risk classification drives the depth of documentation and review requirements. High-risk systems demand more rigorous evidence. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Risk level classification | ETH | `risk_level` (low / medium / high / critical) | | EU AI Act risk tier | ETH | `eu_ai_act_risk` (minimal / limited / high / unacceptable) | @@ -63,9 +63,9 @@ Document the intended capabilities of the AI system alongside its known limitati > Transparent documentation of limitations prevents overreliance and supports informed decision-making by operators and users. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Intended use and capabilities | MCARD | Intended Use section, `intended_use` | | Known limitations | MCARD | Limitations section | @@ -88,9 +88,9 @@ Maintain a centralized registry of identified risks, their severity, likelihood, > A living risk registry ensures risks are tracked over time, not just identified once and forgotten. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Risk catalog | AI-RISK-CATALOG.md | Full document | | Individual risk assessments | ETH | Risk Assessment section | @@ -103,7 +103,7 @@ Maintain a centralized registry of identified risks, their severity, likelihood, - [ ] Create or update AI-RISK-CATALOG.md with all identified risks - [ ] Link each risk entry to the corresponding ETH document that provides detailed assessment - [ ] Assign an owner and review date to every cataloged risk -- [ ] Schedule periodic reviews using `devtrail compliance` to verify risk catalog currency +- [ ] Schedule periodic reviews using `straymark compliance` to verify risk catalog currency --- @@ -113,9 +113,9 @@ Assess the potential impacts of the AI system on individuals (rights, safety, we > Impact assessments must consider both intended effects and reasonably foreseeable unintended consequences across all affected parties. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Individual rights impact | DPIA | Rights Impact Assessment section | | Bias and equity impact | ETH | Bias Evaluation section | @@ -133,9 +133,9 @@ Assess the potential impacts of the AI system on individuals (rights, safety, we --- -## Summary: MAP Function to DevTrail Mapping +## Summary: MAP Function to StrayMark Mapping -| Category | Description | Primary DevTrail Document | Key Fields / Sections | +| Category | Description | Primary StrayMark Document | Key Fields / Sections | |----------|-------------|---------------------------|----------------------| | MP-1 | Context Establishment | AILOG, ETH | Context section, Stakeholder Analysis | | MP-2 | Categorization | ETH | `risk_level`, `eu_ai_act_risk`, `nist_genai_risks` | @@ -145,6 +145,6 @@ Assess the potential impacts of the AI system on individuals (rights, safety, we --- -*NIST AI RMF MAP Function Implementation Guide --- DevTrail Framework* +*NIST AI RMF MAP Function Implementation Guide --- StrayMark Framework* - + diff --git a/.devtrail/03-implementation/NIST-AI-RMF-MEASURE-GUIDE.md b/.straymark/03-implementation/NIST-AI-RMF-MEASURE-GUIDE.md similarity index 83% rename from .devtrail/03-implementation/NIST-AI-RMF-MEASURE-GUIDE.md rename to .straymark/03-implementation/NIST-AI-RMF-MEASURE-GUIDE.md index afec79f..4a203fe 100644 --- a/.devtrail/03-implementation/NIST-AI-RMF-MEASURE-GUIDE.md +++ b/.straymark/03-implementation/NIST-AI-RMF-MEASURE-GUIDE.md @@ -13,22 +13,22 @@ Define appropriate metrics for evaluating AI system performance, trustworthiness > Good metrics are specific, consistently measurable, and directly tied to the risks and trustworthiness characteristics that matter for the system. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | KPI definitions | AI-KPIS.md | Full document | | Performance metrics | TES | Performance Metrics section | | Accuracy and reliability metrics | MCARD | Performance Metrics section | -| Documentation health metrics | `devtrail status` | Coverage, staleness, review rates | -| Compliance metrics | `devtrail compliance` | Validation results | +| Documentation health metrics | `straymark status` | Coverage, staleness, review rates | +| Compliance metrics | `straymark compliance` | Validation results | ### Implementation Checklist - [ ] Define key performance indicators in AI-KPIS.md, covering accuracy, fairness, reliability, and safety - [ ] Establish baseline measurements for each metric in TES documents - [ ] Set thresholds and alert conditions for each metric in the MCARD Performance Metrics section -- [ ] Run `devtrail status` regularly to track documentation health as a governance metric +- [ ] Run `straymark status` regularly to track documentation health as a governance metric --- @@ -38,9 +38,9 @@ Assess the AI system against trustworthiness characteristics: validity, reliabil > Trustworthiness is multidimensional. A system can score well on accuracy while failing on fairness or transparency. Evaluation must cover all relevant dimensions. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Bias and fairness evaluation | ETH | Bias Evaluation section | | Transparency assessment | ETH | Transparency section | @@ -65,12 +65,12 @@ Track identified risks over time, monitoring changes in severity, likelihood, an > Risk tracking transforms a static risk register into a living governance instrument that reflects actual system behavior and changing conditions. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Risk status over time | AI-RISK-CATALOG.md | Review Date, Status columns | -| Compliance validation | `devtrail compliance` | Validation output | +| Compliance validation | `straymark compliance` | Validation output | | Risk level changes | ETH | `risk_level` field (tracked across versions) | | Control effectiveness | AI-RISK-CATALOG.md | Current Controls, Residual Risk columns | | Trend analysis | AI-KPIS.md | Trend metrics section | @@ -78,7 +78,7 @@ Track identified risks over time, monitoring changes in severity, likelihood, an ### Implementation Checklist - [ ] Set review dates for every entry in AI-RISK-CATALOG.md and honor them -- [ ] Run `devtrail compliance` as part of CI to detect documentation gaps and stale risk assessments +- [ ] Run `straymark compliance` as part of CI to detect documentation gaps and stale risk assessments - [ ] Update the ETH `risk_level` field when new evidence changes the risk profile - [ ] Record control effectiveness observations during each risk review cycle @@ -90,9 +90,9 @@ Incorporate feedback from users, operators, incident reports, and monitoring dat > Feedback loops close the gap between theoretical risk assessments and observed real-world behavior. Without them, risk management becomes disconnected from reality. -### DevTrail Mapping +### StrayMark Mapping -| NIST Requirement | DevTrail Document | Section / Field | +| NIST Requirement | StrayMark Document | Section / Field | |------------------|-------------------|-----------------| | Incident post-mortems | INC | Post-Mortem Analysis section | | User feedback integration | MANAGEMENT-REVIEW-TEMPLATE.md | Feedback Summary section | @@ -109,17 +109,17 @@ Incorporate feedback from users, operators, incident reports, and monitoring dat --- -## Summary: MEASURE Function to DevTrail Mapping +## Summary: MEASURE Function to StrayMark Mapping -| Category | Description | Primary DevTrail Document | Key Fields / Sections | +| Category | Description | Primary StrayMark Document | Key Fields / Sections | |----------|-------------|---------------------------|----------------------| | MS-1 | Metrics Identification | AI-KPIS.md, TES | KPI definitions, Performance Metrics | | MS-2 | Trustworthiness Evaluation | ETH, MCARD | Bias Evaluation, Performance Metrics | -| MS-3 | Risk Tracking | AI-RISK-CATALOG.md | Review Date, Status, `devtrail compliance` | +| MS-3 | Risk Tracking | AI-RISK-CATALOG.md | Review Date, Status, `straymark compliance` | | MS-4 | Feedback Integration | INC, MANAGEMENT-REVIEW-TEMPLATE.md | Post-Mortem Analysis, Action Items | --- -*NIST AI RMF MEASURE Function Implementation Guide --- DevTrail Framework* +*NIST AI RMF MEASURE Function Implementation Guide --- StrayMark Framework* - + diff --git a/.devtrail/03-implementation/i18n/es/NIST-AI-600-1-GENAI-RISKS.md b/.straymark/03-implementation/i18n/es/NIST-AI-600-1-GENAI-RISKS.md similarity index 96% rename from .devtrail/03-implementation/i18n/es/NIST-AI-600-1-GENAI-RISKS.md rename to .straymark/03-implementation/i18n/es/NIST-AI-600-1-GENAI-RISKS.md index 949820d..066b83a 100644 --- a/.devtrail/03-implementation/i18n/es/NIST-AI-600-1-GENAI-RISKS.md +++ b/.straymark/03-implementation/i18n/es/NIST-AI-600-1-GENAI-RISKS.md @@ -2,7 +2,7 @@ > **Estándar**: NIST AI 600-1 --- Artificial Intelligence Risk Management Framework: Generative AI Profile > -> NIST AI 600-1 define 12 categorías de riesgo específicas para sistemas de IA generativa. Esta referencia mapea cada categoría a las plantillas de DevTrail, valores de frontmatter y mitigaciones prácticas. Úsela junto con las guías de funciones del NIST AI RMF para asegurar una cobertura integral de riesgos de GenAI. +> NIST AI 600-1 define 12 categorías de riesgo específicas para sistemas de IA generativa. Esta referencia mapea cada categoría a las plantillas de StrayMark, valores de frontmatter y mitigaciones prácticas. Úsela junto con las guías de funciones del NIST AI RMF para asegurar una cobertura integral de riesgos de GenAI. --- @@ -16,7 +16,7 @@ Los sistemas de IA generativa pueden producir información que podría asistir e - Un modelo de generación de código produce código de explotación funcional dirigido a sistemas de control de infraestructura crítica - Un asistente de IA responde a consultas sobre el cultivo de agentes biológicos con detalle procesable -### Mapeo DevTrail +### Mapeo StrayMark | Aspecto | Valor | |--------|-------| @@ -43,7 +43,7 @@ Los sistemas de IA generativa pueden producir salidas que son factualmente incor - Un modelo de generación de código inventa métodos de API que no forman parte de la biblioteca referenciada - Una IA conversacional proporciona información médica que contradice las guías clínicas establecidas -### Mapeo DevTrail +### Mapeo StrayMark | Aspecto | Valor | |--------|-------| @@ -70,7 +70,7 @@ Los sistemas de IA generativa pueden generar contenido que promueva, glorifique - Un modelo de generación de imágenes crea representaciones realistas de violencia gráfica bajo solicitud - Un chatbot proporciona instrucciones detalladas de autolesiones cuando es consultado por un usuario vulnerable -### Mapeo DevTrail +### Mapeo StrayMark | Aspecto | Valor | |--------|-------| @@ -97,7 +97,7 @@ Los sistemas de IA generativa pueden memorizar, filtrar o revelar inadvertidamen - Una IA conversacional retiene y muestra información de la sesión de un usuario a otro - Un modelo entrenado con datos propietarios filtra secretos comerciales a través de prompts cuidadosamente elaborados -### Mapeo DevTrail +### Mapeo StrayMark | Aspecto | Valor | |--------|-------| @@ -124,7 +124,7 @@ El entrenamiento, ajuste fino e inferencia de modelos de IA generativa consumen - Los ciclos de reentrenamiento frecuentes multiplican el costo ambiental sin ganancias proporcionales de capacidad - Desplegar inferencia a escala genera un consumo energético sostenido a través de la infraestructura de centros de datos -### Mapeo DevTrail +### Mapeo StrayMark | Aspecto | Valor | |--------|-------| @@ -151,7 +151,7 @@ Los sistemas de IA generativa pueden amplificar sesgos sociales presentes en los - Un modelo de texto asocia estereotipos negativos con nacionalidades o géneros específicos - El uso generalizado de un único asistente de escritura de IA homogeneiza los estilos de comunicación en toda una industria -### Mapeo DevTrail +### Mapeo StrayMark | Aspecto | Valor | |--------|-------| @@ -178,7 +178,7 @@ Riesgos derivados de niveles inadecuados de supervisión humana, dependencia exc - Un sistema se despliega sin rutas claras de escalamiento para casos donde se necesita el juicio humano - Los usuarios desarrollan una confianza excesiva en las salidas de IA después de una interacción prolongada sin encontrar errores -### Mapeo DevTrail +### Mapeo StrayMark | Aspecto | Valor | |--------|-------| @@ -205,7 +205,7 @@ La IA generativa puede usarse para crear o amplificar desinformación, informaci - Medios deepfake generados por IA se usan para suplantar a figuras públicas en campañas de desinformación - La generación automatizada de contenido inunda los canales de información con contenido de baja calidad y engañoso a escala -### Mapeo DevTrail +### Mapeo StrayMark | Aspecto | Valor | |--------|-------| @@ -232,7 +232,7 @@ Los sistemas de IA generativa introducen nuevas superficies de ataque, incluyend - Un modelo es manipulado a través de entradas adversariales para producir salidas que evaden los filtros de contenido - El envenenamiento de datos de entrenamiento causa que un modelo produzca salidas sutilmente incorrectas en dominios específicos -### Mapeo DevTrail +### Mapeo StrayMark | Aspecto | Valor | |--------|-------| @@ -259,7 +259,7 @@ La IA generativa puede infringir derechos de propiedad intelectual al reproducir - Un modelo de generación de imágenes produce salidas que replican de cerca el estilo distintivo de un artista vivo - Un modelo entrenado con documentos corporativos propietarios genera salidas que revelan secretos comerciales protegidos -### Mapeo DevTrail +### Mapeo StrayMark | Aspecto | Valor | |--------|-------| @@ -286,7 +286,7 @@ Los sistemas de IA generativa pueden producir contenido sexualmente explícito, - Un modelo de texto genera descripciones degradantes de individuos basadas en sus características demográficas - Un sistema de IA produce imágenes íntimas no consentidas combinando fotografías disponibles públicamente con técnicas generativas -### Mapeo DevTrail +### Mapeo StrayMark | Aspecto | Valor | |--------|-------| @@ -313,7 +313,7 @@ Riesgos derivados de la integración de componentes de IA de terceros, modelos, - Un proveedor de API cambia el comportamiento del modelo sin previo aviso, rompiendo supuestos en sistemas dependientes - Un modelo ajustado hereda vulnerabilidades no reveladas de su modelo base -### Mapeo DevTrail +### Mapeo StrayMark | Aspecto | Valor | |--------|-------| @@ -330,9 +330,9 @@ Riesgos derivados de la integración de componentes de IA de terceros, modelos, --- -## Resumen: Mapeo de Categorías de Riesgo de GenAI a DevTrail +## Resumen: Mapeo de Categorías de Riesgo de GenAI a StrayMark -| Categoría | Identificador | Plantilla DevTrail Principal | Valor de Frontmatter | +| Categoría | Identificador | Plantilla StrayMark Principal | Valor de Frontmatter | |----------|-----------|---------------------------|-------------------| | Información CBRN | `cbrn` | ETH | `nist_genai_risks: [cbrn]` | | Confabulación | `confabulation` | ETH | `nist_genai_risks: [confabulation]` | @@ -349,6 +349,6 @@ Riesgos derivados de la integración de componentes de IA de terceros, modelos, --- -*Referencia de Categorías de Riesgo de IA Generativa NIST AI 600-1 --- DevTrail Framework* +*Referencia de Categorías de Riesgo de IA Generativa NIST AI 600-1 --- StrayMark Framework* - + diff --git a/.devtrail/03-implementation/i18n/es/NIST-AI-RMF-GOVERN-GUIDE.md b/.straymark/03-implementation/i18n/es/NIST-AI-RMF-GOVERN-GUIDE.md similarity index 92% rename from .devtrail/03-implementation/i18n/es/NIST-AI-RMF-GOVERN-GUIDE.md rename to .straymark/03-implementation/i18n/es/NIST-AI-RMF-GOVERN-GUIDE.md index af16bd6..bc23259 100644 --- a/.devtrail/03-implementation/i18n/es/NIST-AI-RMF-GOVERN-GUIDE.md +++ b/.straymark/03-implementation/i18n/es/NIST-AI-RMF-GOVERN-GUIDE.md @@ -13,9 +13,9 @@ Establecer, documentar y comunicar políticas organizacionales que definan las e > Las políticas establecen la línea base organizacional. Sin políticas explícitas, los equipos recurren a juicios individuales inconsistentes. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Política de gobernanza de IA | AI-GOVERNANCE-POLICY.md | Documento completo | | Estándares de documentación | DOCUMENTATION-POLICY.md | Documento completo | @@ -38,9 +38,9 @@ Definir roles, responsabilidades y estructuras de rendición de cuentas claras p > La responsabilidad sin asignación es una ilusión. Cada actividad de gestión de riesgos necesita una parte responsable designada. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Roles y responsabilidades | AI-GOVERNANCE-POLICY.md | Sección 2.2 (Roles and Responsibilities) | | Límites de autonomía de agentes | AGENT-RULES.md | Autonomy Table, Human Review Triggers | @@ -63,9 +63,9 @@ Asegurar que los equipos de desarrollo y gobernanza de IA incluyan perspectivas > Los equipos homogéneos producen evaluaciones de riesgos homogéneas. La diversidad de perspectivas es un control de gobernanza, no solo un objetivo de recursos humanos. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Guía de composición de equipos | AI-GOVERNANCE-POLICY.md | Sección 4 (Support and Resources) | | Requisitos de competencia | AI-GOVERNANCE-POLICY.md | Sección 4.2 (Competencies) | @@ -87,9 +87,9 @@ Fomentar una cultura organizacional que valore el desarrollo responsable de IA, > La cultura determina si las políticas se siguen en la práctica o existen solo en papel. La gobernanza es tan fuerte como la cultura que la sostiene. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Principios organizacionales | PRINCIPLES.md | Documento completo | | Directrices éticas | PRINCIPLES.md | sección Core Principles | @@ -111,9 +111,9 @@ Involucrar a las partes interesadas internas y externas regularmente en las acti > La gobernanza realizada de forma aislada carece de la perspectiva externa necesaria para anticipar los impactos del mundo real. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Revisiones de gestión | MANAGEMENT-REVIEW-TEMPLATE.md | Documento completo | | Retroalimentación de partes interesadas | MANAGEMENT-REVIEW-TEMPLATE.md | sección Feedback Summary | @@ -136,9 +136,9 @@ Gobernar la cadena de suministro de IA manteniendo transparencia sobre component > No se puede gestionar lo que no se puede ver. La gobernanza de la cadena de suministro comienza con un inventario completo y actualizado. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Inventario de componentes | SBOM | Documento completo | | Servicios de terceros | SBOM | sección Third-Party Services | @@ -155,9 +155,9 @@ Gobernar la cadena de suministro de IA manteniendo transparencia sobre component --- -## Resumen: Mapeo de la Función GOVERN a DevTrail +## Resumen: Mapeo de la Función GOVERN a StrayMark -| Categoría | Descripción | Documento DevTrail Principal | Campos / Secciones Clave | +| Categoría | Descripción | Documento StrayMark Principal | Campos / Secciones Clave | |----------|-------------|---------------------------|----------------------| | GV-1 | Políticas | AI-GOVERNANCE-POLICY.md, DOCUMENTATION-POLICY.md | Documentos completos | | GV-2 | Responsabilidad | AGENT-RULES.md, AI-GOVERNANCE-POLICY.md | Autonomy Table, Sección 2.2 | @@ -168,6 +168,6 @@ Gobernar la cadena de suministro de IA manteniendo transparencia sobre component --- -*Guía de Implementación de la Función GOVERN del NIST AI RMF --- DevTrail Framework* +*Guía de Implementación de la Función GOVERN del NIST AI RMF --- StrayMark Framework* - + diff --git a/.devtrail/03-implementation/i18n/es/NIST-AI-RMF-MANAGE-GUIDE.md b/.straymark/03-implementation/i18n/es/NIST-AI-RMF-MANAGE-GUIDE.md similarity index 90% rename from .devtrail/03-implementation/i18n/es/NIST-AI-RMF-MANAGE-GUIDE.md rename to .straymark/03-implementation/i18n/es/NIST-AI-RMF-MANAGE-GUIDE.md index cc1cd8a..259f898 100644 --- a/.devtrail/03-implementation/i18n/es/NIST-AI-RMF-MANAGE-GUIDE.md +++ b/.straymark/03-implementation/i18n/es/NIST-AI-RMF-MANAGE-GUIDE.md @@ -13,9 +13,9 @@ Planificar y ejecutar respuestas a los riesgos identificados. Las respuestas a r > Cada riesgo identificado debe tener una estrategia de respuesta explícita. La aceptación de riesgos no documentada es negligencia implícita. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Decisiones de respuesta a riesgos | ADR | sección Decision and Rationale | | Mitigaciones recomendadas | ETH | sección Recommendations | @@ -38,9 +38,9 @@ Implementar controles técnicos y organizacionales específicos para reducir la > Las mitigaciones deben verificarse, no asumirse. Implementar controles, probarlos y documentar la evidencia de su efectividad. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Controles de seguridad | SEC | sección Controls Implemented | | Mitigaciones de privacidad | DPIA | sección Mitigation Measures | @@ -63,9 +63,9 @@ Gestionar los riesgos derivados de componentes de IA de terceros, modelos, fuent > Los componentes de terceros heredan y propagan riesgos. Las organizaciones siguen siendo responsables de los riesgos introducidos por sus proveedores. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Inventario de terceros | SBOM | secciones Third-Party Services, Components | | Evaluación de riesgos de componentes | SBOM | sección Risk Assessment | @@ -88,15 +88,15 @@ Monitorear los sistemas de IA desplegados para detectar degradación del rendimi > El despliegue no es el fin de la gestión de riesgos --- es donde los riesgos del mundo real comienzan a manifestarse. El monitoreo continuo es esencial. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Seguimiento de incidentes | INC | Documento completo | | Estado del ciclo de vida | AI-LIFECYCLE-TRACKER.md | sección Monitoring Phase | | Monitoreo operacional | AILOG | Entradas de monitoring and observability | | Detección de deriva del rendimiento | TES | Pruebas de regresión y deriva | -| Salud del sistema | `devtrail status` | Métricas de salud de la documentación | +| Salud del sistema | `straymark status` | Métricas de salud de la documentación | ### Lista de Verificación de Implementación @@ -107,9 +107,9 @@ Monitorear los sistemas de IA desplegados para detectar degradación del rendimi --- -## Resumen: Mapeo de la Función MANAGE a DevTrail +## Resumen: Mapeo de la Función MANAGE a StrayMark -| Categoría | Descripción | Documento DevTrail Principal | Campos / Secciones Clave | +| Categoría | Descripción | Documento StrayMark Principal | Campos / Secciones Clave | |----------|-------------|---------------------------|----------------------| | MG-1 | Respuesta a Riesgos | ETH, ADR | Recommendations, Decision and Rationale | | MG-2 | Mitigación de Riesgos | SEC, DPIA | Controls Implemented, Mitigation Measures | @@ -118,6 +118,6 @@ Monitorear los sistemas de IA desplegados para detectar degradación del rendimi --- -*Guía de Implementación de la Función MANAGE del NIST AI RMF --- DevTrail Framework* +*Guía de Implementación de la Función MANAGE del NIST AI RMF --- StrayMark Framework* - + diff --git a/.devtrail/03-implementation/i18n/es/NIST-AI-RMF-MAP-GUIDE.md b/.straymark/03-implementation/i18n/es/NIST-AI-RMF-MAP-GUIDE.md similarity index 90% rename from .devtrail/03-implementation/i18n/es/NIST-AI-RMF-MAP-GUIDE.md rename to .straymark/03-implementation/i18n/es/NIST-AI-RMF-MAP-GUIDE.md index 45f3543..8f065a8 100644 --- a/.devtrail/03-implementation/i18n/es/NIST-AI-RMF-MAP-GUIDE.md +++ b/.straymark/03-implementation/i18n/es/NIST-AI-RMF-MAP-GUIDE.md @@ -13,9 +13,9 @@ Documentar el propósito del sistema de IA, el entorno operativo, las partes int > Establecer un contexto exhaustivo garantiza que las evaluaciones de riesgos se fundamenten en las condiciones reales de despliegue del sistema, en lugar de suposiciones genéricas. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Propósito y alcance del sistema | AILOG | `title`, sección Summary | | Entorno operativo | AILOG | sección Context | @@ -38,9 +38,9 @@ Clasificar los sistemas de IA por nivel de riesgo según su uso previsto, el pot > La clasificación de riesgos determina la profundidad de los requisitos de documentación y revisión. Los sistemas de alto riesgo exigen evidencia más rigurosa. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Clasificación del nivel de riesgo | ETH | `risk_level` (low / medium / high / critical) | | Nivel de riesgo EU AI Act | ETH | `eu_ai_act_risk` (minimal / limited / high / unacceptable) | @@ -63,9 +63,9 @@ Documentar las capacidades previstas del sistema de IA junto con sus limitacione > La documentación transparente de las limitaciones previene la dependencia excesiva y respalda la toma de decisiones informada por parte de operadores y usuarios. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Uso previsto y capacidades | MCARD | sección Intended Use, `intended_use` | | Limitaciones conocidas | MCARD | sección Limitations | @@ -88,9 +88,9 @@ Mantener un registro centralizado de los riesgos identificados, su severidad, pr > Un registro de riesgos dinámico asegura que los riesgos se rastreen a lo largo del tiempo, no solo se identifiquen una vez y se olviden. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Catálogo de riesgos | AI-RISK-CATALOG.md | Documento completo | | Evaluaciones de riesgos individuales | ETH | sección Risk Assessment | @@ -103,7 +103,7 @@ Mantener un registro centralizado de los riesgos identificados, su severidad, pr - [ ] Crear o actualizar AI-RISK-CATALOG.md con todos los riesgos identificados - [ ] Vincular cada entrada de riesgo al documento ETH correspondiente que proporciona la evaluación detallada - [ ] Asignar un responsable y una fecha de revisión a cada riesgo catalogado -- [ ] Programar revisiones periódicas usando `devtrail compliance` para verificar la vigencia del catálogo de riesgos +- [ ] Programar revisiones periódicas usando `straymark compliance` para verificar la vigencia del catálogo de riesgos --- @@ -113,9 +113,9 @@ Evaluar los impactos potenciales del sistema de IA sobre individuos (derechos, s > Las evaluaciones de impacto deben considerar tanto los efectos previstos como las consecuencias no intencionadas razonablemente previsibles en todas las partes afectadas. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Impacto en derechos individuales | DPIA | sección Rights Impact Assessment | | Impacto de sesgo y equidad | ETH | sección Bias Evaluation | @@ -133,9 +133,9 @@ Evaluar los impactos potenciales del sistema de IA sobre individuos (derechos, s --- -## Resumen: Mapeo de la Función MAP a DevTrail +## Resumen: Mapeo de la Función MAP a StrayMark -| Categoría | Descripción | Documento DevTrail Principal | Campos / Secciones Clave | +| Categoría | Descripción | Documento StrayMark Principal | Campos / Secciones Clave | |----------|-------------|---------------------------|----------------------| | MP-1 | Establecimiento de Contexto | AILOG, ETH | sección Context, Stakeholder Analysis | | MP-2 | Categorización | ETH | `risk_level`, `eu_ai_act_risk`, `nist_genai_risks` | @@ -145,6 +145,6 @@ Evaluar los impactos potenciales del sistema de IA sobre individuos (derechos, s --- -*Guía de Implementación de la Función MAP del NIST AI RMF --- DevTrail Framework* +*Guía de Implementación de la Función MAP del NIST AI RMF --- StrayMark Framework* - + diff --git a/.devtrail/03-implementation/i18n/es/NIST-AI-RMF-MEASURE-GUIDE.md b/.straymark/03-implementation/i18n/es/NIST-AI-RMF-MEASURE-GUIDE.md similarity index 84% rename from .devtrail/03-implementation/i18n/es/NIST-AI-RMF-MEASURE-GUIDE.md rename to .straymark/03-implementation/i18n/es/NIST-AI-RMF-MEASURE-GUIDE.md index 35d3731..8f2df13 100644 --- a/.devtrail/03-implementation/i18n/es/NIST-AI-RMF-MEASURE-GUIDE.md +++ b/.straymark/03-implementation/i18n/es/NIST-AI-RMF-MEASURE-GUIDE.md @@ -13,22 +13,22 @@ Definir métricas apropiadas para evaluar el rendimiento, la confiabilidad y el > Las buenas métricas son específicas, medibles de forma consistente y están directamente vinculadas a los riesgos y características de confiabilidad que importan para el sistema. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Definiciones de KPI | AI-KPIS.md | Documento completo | | Métricas de rendimiento | TES | sección Performance Metrics | | Métricas de precisión y fiabilidad | MCARD | sección Performance Metrics | -| Métricas de salud de la documentación | `devtrail status` | Cobertura, obsolescencia, tasas de revisión | -| Métricas de cumplimiento | `devtrail compliance` | Resultados de validación | +| Métricas de salud de la documentación | `straymark status` | Cobertura, obsolescencia, tasas de revisión | +| Métricas de cumplimiento | `straymark compliance` | Resultados de validación | ### Lista de Verificación de Implementación - [ ] Definir indicadores clave de rendimiento en AI-KPIS.md, cubriendo precisión, equidad, fiabilidad y seguridad - [ ] Establecer mediciones base para cada métrica en documentos TES - [ ] Fijar umbrales y condiciones de alerta para cada métrica en la sección Performance Metrics del MCARD -- [ ] Ejecutar `devtrail status` regularmente para rastrear la salud de la documentación como métrica de gobernanza +- [ ] Ejecutar `straymark status` regularmente para rastrear la salud de la documentación como métrica de gobernanza --- @@ -38,9 +38,9 @@ Evaluar el sistema de IA contra las características de confiabilidad: validez, > La confiabilidad es multidimensional. Un sistema puede obtener buenos resultados en precisión mientras falla en equidad o transparencia. La evaluación debe cubrir todas las dimensiones relevantes. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Evaluación de sesgo y equidad | ETH | sección Bias Evaluation | | Evaluación de transparencia | ETH | sección Transparency | @@ -65,12 +65,12 @@ Rastrear los riesgos identificados a lo largo del tiempo, monitoreando cambios e > El seguimiento de riesgos transforma un registro de riesgos estático en un instrumento de gobernanza dinámico que refleja el comportamiento real del sistema y las condiciones cambiantes. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Estado del riesgo a lo largo del tiempo | AI-RISK-CATALOG.md | columnas Review Date, Status | -| Validación de cumplimiento | `devtrail compliance` | Salida de validación | +| Validación de cumplimiento | `straymark compliance` | Salida de validación | | Cambios en el nivel de riesgo | ETH | campo `risk_level` (rastreado entre versiones) | | Efectividad de controles | AI-RISK-CATALOG.md | columnas Current Controls, Residual Risk | | Análisis de tendencias | AI-KPIS.md | sección Trend metrics | @@ -78,7 +78,7 @@ Rastrear los riesgos identificados a lo largo del tiempo, monitoreando cambios e ### Lista de Verificación de Implementación - [ ] Establecer fechas de revisión para cada entrada en AI-RISK-CATALOG.md y respetarlas -- [ ] Ejecutar `devtrail compliance` como parte del CI para detectar brechas en la documentación y evaluaciones de riesgos obsoletas +- [ ] Ejecutar `straymark compliance` como parte del CI para detectar brechas en la documentación y evaluaciones de riesgos obsoletas - [ ] Actualizar el campo `risk_level` del ETH cuando nueva evidencia cambie el perfil de riesgo - [ ] Registrar observaciones sobre la efectividad de los controles durante cada ciclo de revisión de riesgos @@ -90,9 +90,9 @@ Incorporar la retroalimentación de usuarios, operadores, informes de incidentes > Los ciclos de retroalimentación cierran la brecha entre las evaluaciones teóricas de riesgos y el comportamiento observado en el mundo real. Sin ellos, la gestión de riesgos se desconecta de la realidad. -### Mapeo DevTrail +### Mapeo StrayMark -| Requisito NIST | Documento DevTrail | Sección / Campo | +| Requisito NIST | Documento StrayMark | Sección / Campo | |------------------|-------------------|-----------------| | Post-mortems de incidentes | INC | sección Post-Mortem Analysis | | Integración de retroalimentación de usuarios | MANAGEMENT-REVIEW-TEMPLATE.md | sección Feedback Summary | @@ -109,17 +109,17 @@ Incorporar la retroalimentación de usuarios, operadores, informes de incidentes --- -## Resumen: Mapeo de la Función MEASURE a DevTrail +## Resumen: Mapeo de la Función MEASURE a StrayMark -| Categoría | Descripción | Documento DevTrail Principal | Campos / Secciones Clave | +| Categoría | Descripción | Documento StrayMark Principal | Campos / Secciones Clave | |----------|-------------|---------------------------|----------------------| | MS-1 | Identificación de Métricas | AI-KPIS.md, TES | Definiciones de KPI, Performance Metrics | | MS-2 | Evaluación de Confiabilidad | ETH, MCARD | Bias Evaluation, Performance Metrics | -| MS-3 | Seguimiento de Riesgos | AI-RISK-CATALOG.md | Review Date, Status, `devtrail compliance` | +| MS-3 | Seguimiento de Riesgos | AI-RISK-CATALOG.md | Review Date, Status, `straymark compliance` | | MS-4 | Integración de Retroalimentación | INC, MANAGEMENT-REVIEW-TEMPLATE.md | Post-Mortem Analysis, Action Items | --- -*Guía de Implementación de la Función MEASURE del NIST AI RMF --- DevTrail Framework* +*Guía de Implementación de la Función MEASURE del NIST AI RMF --- StrayMark Framework* - + diff --git a/.straymark/03-implementation/i18n/zh-CN/NIST-AI-600-1-GENAI-RISKS.md b/.straymark/03-implementation/i18n/zh-CN/NIST-AI-600-1-GENAI-RISKS.md new file mode 100644 index 0000000..73911a7 --- /dev/null +++ b/.straymark/03-implementation/i18n/zh-CN/NIST-AI-600-1-GENAI-RISKS.md @@ -0,0 +1,354 @@ +# NIST AI 600-1 --- 生成式 AI 风险类别参考 + +> **标准**: NIST AI 600-1 --- Artificial Intelligence Risk Management Framework: Generative AI Profile +> +> NIST AI 600-1 定义了 12 个生成式 AI 系统特有的风险类别。本参考文档将每个类别映射到 StrayMark 模板、frontmatter 值和实际缓解措施。请结合 NIST AI RMF 功能指南使用本文档，以确保全面覆盖生成式 AI 风险。 + +--- + +## 1. CBRN Information + +**标识符**: `cbrn` + +生成式 AI 系统可能生成有助于制造、获取或部署化学、生物、放射性或核 (CBRN) 武器或材料的信息。 + +- 大型语言模型提供受管控化学物质的逐步合成说明 +- 代码生成模型生成针对关键基础设施控制系统的功能性漏洞利用代码 +- AI 助手以可操作的细节回应有关生物制剂培养的查询 + +### StrayMark 映射 + +| 方面 | 值 | +|--------|-------| +| 主要模板 | ETH | +| Frontmatter 值 | `nist_genai_risks: [cbrn]` | +| 关键部分 | 风险评估、建议 | +| 辅助文档 | SEC（输出过滤控制） | + +### 建议缓解措施 + +- 实施输出过滤和内容安全分类器以检测 CBRN 相关内容 +- 通过微调或系统提示限制模型在 CBRN 相邻领域的能力 +- 为触发 CBRN 安全标记的查询建立人工审查工作流 + +--- + +## 2. Confabulation + +**标识符**: `confabulation` + +生成式 AI 系统可能产生事实错误、虚构的或与训练数据不一致的输出，同时以高度自信的方式呈现这些输出。 + +- 摘要模型编造源材料中不存在的引用 +- 代码生成模型发明不属于引用库的 API 方法 +- 对话式 AI 提供与既定临床指南相矛盾的医疗信息 + +### StrayMark 映射 + +| 方面 | 值 | +|--------|-------| +| 主要模板 | ETH | +| Frontmatter 值 | `nist_genai_risks: [confabulation]` | +| 关键部分 | 风险评估、透明度、建议 | +| 辅助文档 | MCARD（局限性部分）、TES（准确性测试） | + +### 建议缓解措施 + +- 实施检索增强生成 (RAG) 以将输出建立在经过验证的来源基础上 +- 为模型输出添加置信度指标和来源归属 +- 创建包含事实准确性基准和幻觉检测测试的 TES 文档 + +--- + +## 3. Dangerous, Violent, or Hateful Content + +**标识符**: `dangerous_content` + +生成式 AI 系统可能生成宣传、美化或提供暴力、自残或针对个人或群体仇恨的指导性内容。 + +- 文本生成模型产生煽动对特定群体施暴的内容 +- 图像生成模型根据请求创建逼真的暴力图形描述 +- 聊天机器人在受到弱势用户提示时提供详细的自残指导 + +### StrayMark 映射 + +| 方面 | 值 | +|--------|-------| +| 主要模板 | ETH | +| Frontmatter 值 | `nist_genai_risks: [dangerous_content]` | +| 关键部分 | 风险评估、偏见评估、建议 | +| 辅助文档 | SEC（内容审核控制） | + +### 建议缓解措施 + +- 在输入和输出端部署内容安全分类器 +- 实施针对检测到的有害内容尝试的升级协议 +- 通过对抗性红队测试验证内容过滤的有效性（记录在 TES 中） + +--- + +## 4. Data Privacy + +**标识符**: `privacy` + +生成式 AI 系统可能记忆、泄露或无意中揭示训练数据或用户交互中的个人数据、敏感信息或隐私细节。 + +- 语言模型逐字复制训练数据中包含个人可识别信息的段落 +- 对话式 AI 保留并在另一个用户的会话中显示某个用户的信息 +- 在专有数据上训练的模型通过精心设计的提示泄露商业秘密 + +### StrayMark 映射 + +| 方面 | 值 | +|--------|-------| +| 主要模板 | ETH、DPIA | +| Frontmatter 值 | `nist_genai_risks: [privacy]` | +| 关键部分 | 数据隐私部分（ETH）、完整 DPIA | +| 辅助文档 | SEC（访问控制、数据隔离） | + +### 建议缓解措施 + +- 在部署基于个人数据训练或处理个人数据的系统之前进行 DPIA +- 在训练管道中实施差分隐私技术或数据脱敏 +- 测试记忆化和数据提取漏洞（记录在 TES 中） + +--- + +## 5. Environmental Impacts + +**标识符**: `environmental` + +生成式 AI 模型的训练、微调和推理消耗大量计算资源，导致能源使用、碳排放和电子废弃物的增加。 + +- 训练大型基础模型消耗的能源相当于数百个家庭一年的用电量 +- 频繁的重新训练周期成倍增加环境成本，而能力提升并不成比例 +- 大规模部署推理在数据中心基础设施中产生持续的能源消耗 + +### StrayMark 映射 + +| 方面 | 值 | +|--------|-------| +| 主要模板 | ETH | +| Frontmatter 值 | `nist_genai_risks: [environmental]` | +| 关键部分 | 环境影响部分 | +| 辅助文档 | MCARD（计算需求）、AI-KPIS.md（效率指标） | + +### 建议缓解措施 + +- 在 MCARD 中记录计算需求和能源估算 +- 在 AI-KPIS.md 中跟踪和报告碳足迹指标 +- 在 ADR 文档中评估模型效率替代方案（更小的模型、蒸馏、量化） + +--- + +## 6. Harmful Bias and Homogenization + +**标识符**: `bias` + +生成式 AI 系统可能放大训练数据中存在的社会偏见，产生歧视或错误描述特定群体的输出。当 AI 被广泛使用时，同质化现象会减少思想和表达的多样性。 + +- 图像生成模型在专业场景中持续低估某些人口群体的代表性 +- 文本模型将负面刻板印象与特定国籍或性别相关联 +- 广泛使用单一 AI 写作助手使整个行业的沟通风格趋于同质化 + +### StrayMark 映射 + +| 方面 | 值 | +|--------|-------| +| 主要模板 | ETH | +| Frontmatter 值 | `nist_genai_risks: [bias]` | +| 关键部分 | 偏见评估、社会影响、建议 | +| 辅助文档 | TES（公平性测试）、MCARD（训练数据文档） | + +### 建议缓解措施 + +- 在相关人口统计维度上进行偏见评估（记录在 ETH 偏见评估部分） +- 在 TES 文档中实施公平性指标并测试差异性影响 +- 在 MCARD 中记录训练数据组成和已知的代表性差距 + +--- + +## 7. Human-AI Configuration + +**标识符**: `human_ai_config` + +由于人工监督水平不当、对 AI 输出的过度依赖、自动化偏见或人机交互边界配置不当而产生的风险。 + +- 操作员因自动化偏见在未经有意义审查的情况下盲目批准 AI 建议 +- 系统部署时缺乏需要人类判断的情况下的明确升级路径 +- 用户在长期交互中未遇到错误后对 AI 输出产生过度信任 + +### StrayMark 映射 + +| 方面 | 值 | +|--------|-------| +| 主要模板 | ETH | +| Frontmatter 值 | `nist_genai_risks: [human_ai_config]` | +| 关键部分 | 风险评估、建议 | +| 辅助文档 | AGENT-RULES.md（自主权限制）、MCARD（预期使用边界） | + +### 建议缓解措施 + +- 在 AGENT-RULES.md 中为每个自主级别定义明确的人工监督要求 +- 在 MCARD 的预期用途部分记录预期的人机交互模式 +- 为高风险决策实施强制人工审查检查点（记录在 ADR 中） + +--- + +## 8. Information Integrity + +**标识符**: `information_integrity` + +生成式 AI 可被用于创建或放大错误信息、虚假信息和篡改媒体，破坏公众信任和信息生态系统的完整性。 + +- 模型生成高度逼真但虚构的新闻文章，与合法新闻无法区分 +- AI 生成的深度伪造媒体被用于冒充公众人物进行虚假信息运动 +- 自动化内容生成大规模地向信息渠道注入低质量、误导性内容 + +### StrayMark 映射 + +| 方面 | 值 | +|--------|-------| +| 主要模板 | ETH | +| Frontmatter 值 | `nist_genai_risks: [information_integrity]` | +| 关键部分 | 风险评估、透明度、社会影响 | +| 辅助文档 | SEC（来源控制）、MCARD（输出水印） | + +### 建议缓解措施 + +- 为 AI 生成的输出实施内容来源追溯和水印（在 ADR 中记录方法） +- 在 AI-GOVERNANCE-POLICY.md 中建立禁止欺骗性使用的使用策略并进行记录 +- 在下游系统中部署篡改或 AI 生成内容的检测机制 + +--- + +## 9. Information Security + +**标识符**: `information_security` + +生成式 AI 系统引入了新型攻击面，包括提示注入、模型提取、训练数据投毒和绕过安全控制的对抗性输入。 + +- 攻击者使用提示注入覆盖系统指令并提取敏感配置 +- 模型通过对抗性输入被操纵以产生绕过内容过滤器的输出 +- 训练数据投毒导致模型在特定领域产生微妙错误的输出 + +### StrayMark 映射 + +| 方面 | 值 | +|--------|-------| +| 主要模板 | SEC | +| Frontmatter 值 | `nist_genai_risks: [information_security]` | +| 关键部分 | 威胁模型、已实施控制、漏洞 | +| 辅助文档 | ETH（风险评估）、TES（安全测试） | + +### 建议缓解措施 + +- 创建包含针对生成式 AI 攻击向量（提示注入、提取、投毒）的威胁模型的 SEC 文档 +- 实施在 SEC 中记录的输入验证和输出清理控制 +- 进行对抗性红队演练并在 TES 中记录结果 + +--- + +## 10. Intellectual Property + +**标识符**: `intellectual_property` + +生成式 AI 可能通过复制受版权保护的材料、生成与受保护作品实质相似的输出或在未经授权的情况下使用专有数据来侵犯知识产权。 + +- 代码生成模型逐字复制训练数据中受版权保护的源代码片段 +- 图像生成模型产生与在世艺术家独特风格高度相似的输出 +- 在专有企业文档上训练的模型生成揭露受保护商业秘密的输出 + +### StrayMark 映射 + +| 方面 | 值 | +|--------|-------| +| 主要模板 | ETH | +| Frontmatter 值 | `nist_genai_risks: [intellectual_property]` | +| 关键部分 | 风险评估、建议 | +| 辅助文档 | SBOM（训练数据来源、许可证合规） | + +### 建议缓解措施 + +- 在 SBOM 中记录训练数据来源及其许可条款 +- 实施输出与已知受版权保护作品的相似性检测 +- 为商业应用中使用的 AI 生成内容建立知识产权审查工作流（记录在 ADR 中） + +--- + +## 11. Obscene or Degrading Content + +**标识符**: `obscene_content` + +生成式 AI 系统可能产生色情、淫秽或贬损性内容，无论是通过直接生成还是通过利用内容过滤器的弱点。 + +- 图像生成模型通过提示工程被操纵以绕过安全过滤器并生成露骨内容 +- 文本模型基于个人的人口统计特征生成贬损性描述 +- AI 系统通过将公开可用的照片与生成技术相结合来生成未经同意的私密图像 + +### StrayMark 映射 + +| 方面 | 值 | +|--------|-------| +| 主要模板 | ETH | +| Frontmatter 值 | `nist_genai_risks: [obscene_content]` | +| 关键部分 | 风险评估、建议 | +| 辅助文档 | SEC（内容过滤控制） | + +### 建议缓解措施 + +- 在输入和输出端部署多层内容安全过滤器 +- 实施能够抵抗常见越狱技术的强健内容分类器 +- 进行专门针对内容过滤器绕过的红队演练（记录在 TES 中） + +--- + +## 12. Value Chain and Component Integration + +**标识符**: `value_chain` + +由于将第三方 AI 组件、模型、数据集和服务集成到更大系统中而产生的风险，其中上游变更、漏洞或质量问题会传播到下游。 + +- 第三方嵌入模型引入微妙的偏见，传播到所有下游应用 +- API 提供商在未通知的情况下更改模型行为，破坏依赖系统中的假设 +- 微调模型继承了其基础模型中未公开的漏洞 + +### StrayMark 映射 + +| 方面 | 值 | +|--------|-------| +| 主要模板 | SBOM | +| Frontmatter 值 | `nist_genai_risks: [value_chain]` | +| 关键部分 | 第三方服务、组件、依赖项 | +| 辅助文档 | ETH（第三方风险）、SEC（供应链安全） | + +### 建议缓解措施 + +- 维护覆盖价值链中所有 AI 组件的全面 SBOM 文档 +- 在 MCARD 中固定模型版本并记录预期行为基线 +- 与 AI 服务提供商建立变更通知的合同要求（记录在 ADR 中） + +--- + +## 摘要：生成式 AI 风险类别到 StrayMark 映射 + +| 类别 | 标识符 | 主要 StrayMark 模板 | Frontmatter 值 | +|----------|-----------|---------------------------|-------------------| +| CBRN Information | `cbrn` | ETH | `nist_genai_risks: [cbrn]` | +| Confabulation | `confabulation` | ETH | `nist_genai_risks: [confabulation]` | +| Dangerous/Violent/Hateful Content | `dangerous_content` | ETH | `nist_genai_risks: [dangerous_content]` | +| Data Privacy | `privacy` | ETH、DPIA | `nist_genai_risks: [privacy]` | +| Environmental Impacts | `environmental` | ETH | `nist_genai_risks: [environmental]` | +| Harmful Bias and Homogenization | `bias` | ETH | `nist_genai_risks: [bias]` | +| Human-AI Configuration | `human_ai_config` | ETH | `nist_genai_risks: [human_ai_config]` | +| Information Integrity | `information_integrity` | ETH | `nist_genai_risks: [information_integrity]` | +| Information Security | `information_security` | SEC | `nist_genai_risks: [information_security]` | +| Intellectual Property | `intellectual_property` | ETH | `nist_genai_risks: [intellectual_property]` | +| Obscene/Degrading Content | `obscene_content` | ETH | `nist_genai_risks: [obscene_content]` | +| Value Chain and Component Integration | `value_chain` | SBOM | `nist_genai_risks: [value_chain]` | + +--- + +*NIST AI 600-1 生成式 AI 风险类别参考 --- StrayMark Framework* + + diff --git a/.straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-GOVERN-GUIDE.md b/.straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-GOVERN-GUIDE.md new file mode 100644 index 0000000..59bfdc3 --- /dev/null +++ b/.straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-GOVERN-GUIDE.md @@ -0,0 +1,173 @@ +# NIST AI RMF --- GOVERN 功能实施指南 + +> **框架**: NIST AI Risk Management Framework (AI RMF 1.0) +> **功能**: GOVERN --- AI 组织治理结构 +> +> GOVERN 功能建立并维护负责任 AI 风险管理所需的组织结构、策略、流程和文化。它是一个跨领域功能，为 MAP、MEASURE 和 MANAGE 功能提供信息，同时也从这些功能中获取信息。 + +--- + +## GV-1: AI 治理策略 + +建立、记录和传达组织策略，定义 AI 开发、部署和使用的期望。策略应当是动态文档，需要定期审查和更新。 + +> 策略设定组织基准。如果没有明确的策略，团队会默认依赖不一致的个人判断。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| AI 治理策略 | AI-GOVERNANCE-POLICY.md | 完整文档 | +| 文档标准 | DOCUMENTATION-POLICY.md | 完整文档 | +| Agent 自主权限制 | AGENT-RULES.md | 自主权表 | +| 伦理原则 | PRINCIPLES.md | 完整文档 | +| 法规合规策略 | AI-GOVERNANCE-POLICY.md | 第 1.3 节（法律和法规要求） | + +### 实施检查清单 + +- [ ] 根据组织的背景、范围和法规环境定制 AI-GOVERNANCE-POLICY.md +- [ ] 采用 DOCUMENTATION-POLICY.md 作为所有 AI 相关文档的标准 +- [ ] 配置 AGENT-RULES.md 以反映组织对 AI Agent 自主权的风险容忍度 +- [ ] 至少每年或在发生重大变更时审查并更新所有治理策略 + +--- + +## GV-2: 问责与角色 + +为 AI 风险管理定义明确的角色、职责和问责结构。确保每个治理功能都有指定的负责人。 + +> 没有分配的问责是一种幻觉。每项风险管理活动都需要一个指定的责任人。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 角色与职责 | AI-GOVERNANCE-POLICY.md | 第 2.2 节（角色与职责） | +| Agent 自主权边界 | AGENT-RULES.md | 自主权表、人工审查触发条件 | +| 决策权限 | ADR | 决策者部分 | +| 审查职责 | DOCUMENTATION-POLICY.md | 审查要求部分 | +| 事件问责 | INC | 负责人、响应人员字段 | + +### 实施检查清单 + +- [ ] 完成 AI-GOVERNANCE-POLICY.md 第 2.2 节中的角色与职责表 +- [ ] 在 AGENT-RULES.md 中为所有高风险活动定义人工审查触发条件 +- [ ] 确保每个 ADR 都标识决策者及其权限 +- [ ] 分配事件响应角色并在 INC 模板中记录 + +--- + +## GV-3: 劳动力多样性与包容性 + +确保 AI 开发和治理团队包含多样化的视角。多样化的团队更善于识别风险、偏见和盲点。 + +> 同质化的团队产生同质化的风险评估。视角的多样性是一种治理控制措施，而不仅仅是人力资源目标。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 团队组成指导 | AI-GOVERNANCE-POLICY.md | 第 4 节（支持与资源） | +| 能力要求 | AI-GOVERNANCE-POLICY.md | 第 4.2 节（能力） | +| 包容性审查流程 | DOCUMENTATION-POLICY.md | 审查要求部分 | +| 利益相关者代表 | ETH | 利益相关者分析部分 | + +### 实施检查清单 + +- [ ] 在 AI-GOVERNANCE-POLICY.md 第 4 节中记录团队组成期望 +- [ ] 定义涵盖技术、伦理、法律和领域专业知识的能力要求 +- [ ] 确保 ETH 利益相关者分析考虑受影响社区的视角 +- [ ] 在高风险文档审查工作流中纳入多样化的审查人员 + +--- + +## GV-4: 组织文化 + +培养重视负责任 AI 开发、鼓励提出关切、支持持续学习 AI 风险和伦理的组织文化。 + +> 文化决定了策略在实践中是否被遵循，还是仅存在于纸面上。治理的力度取决于维系它的文化。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 组织原则 | PRINCIPLES.md | 完整文档 | +| 伦理准则 | PRINCIPLES.md | 核心原则部分 | +| 透明度期望 | AGENT-RULES.md | 文档要求 | +| 从事件中学习 | INC | 经验教训部分 | + +### 实施检查清单 + +- [ ] 采用并传达 PRINCIPLES.md 作为团队共同的伦理基础 +- [ ] 通过将 INC 文档视为学习工具，建立无责文化以鼓励报告 AI 相关问题 +- [ ] 使用 PRINCIPLES.md 和 AI-GOVERNANCE-POLICY.md 将 AI 伦理意识融入入职培训 +- [ ] 表彰和分享记录在 AILOG 和 ETH 记录中的负责任 AI 实践案例 + +--- + +## GV-5: 利益相关者参与 + +定期让内部和外部利益相关者参与 AI 治理活动。利益相关者的参与有助于改善风险识别、建立信任，并确保治理反映多样化的需求。 + +> 在封闭环境中进行的治理缺乏预判现实世界影响所需的外部视角。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 管理评审 | MANAGEMENT-REVIEW-TEMPLATE.md | 完整文档 | +| 利益相关者反馈 | MANAGEMENT-REVIEW-TEMPLATE.md | 反馈摘要部分 | +| 外部沟通 | AI-GOVERNANCE-POLICY.md | 第 4.4 节（沟通） | +| 公共透明度 | MCARD | 完整文档（面向公众的模型文档） | +| 评审结果 | MANAGEMENT-REVIEW-TEMPLATE.md | 行动项部分 | + +### 实施检查清单 + +- [ ] 使用 MANAGEMENT-REVIEW-TEMPLATE.md 安排定期管理评审 +- [ ] 将利益相关者反馈作为管理评审的常设议程项目 +- [ ] 为外部部署的 AI 系统发布 MCARD 文档以支持公共透明度 +- [ ] 记录利益相关者参与活动及其成果作为审计证据 + +--- + +## GV-6: AI 供应链治理 + +通过维护对 AI 系统中使用的第三方组件、模型、数据源和服务的透明度来治理 AI 供应链。 + +> 看不到的东西无法管理。供应链治理始于完整且最新的清单。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 组件清单 | SBOM | 完整文档 | +| 第三方服务 | SBOM | 第三方服务部分 | +| 许可证合规 | SBOM | 许可证列 | +| 供应商风险评估 | ETH | 第三方风险部分 | +| 供应链策略 | AI-GOVERNANCE-POLICY.md | 第 5.3 节（第三方 AI 组件） | + +### 实施检查清单 + +- [ ] 为每个 AI 系统维护最新的 SBOM，包括模型、库、API 和数据源 +- [ ] 在 SBOM 许可证列中跟踪所有第三方组件的许可条款 +- [ ] 对组件影响高风险功能的关键供应商进行 ETH 评估 +- [ ] 在 AI-GOVERNANCE-POLICY.md 第 5.3 节中定义供应链治理要求 + +--- + +## 摘要：GOVERN 功能到 StrayMark 映射 + +| 类别 | 描述 | 主要 StrayMark 文档 | 关键字段 / 部分 | +|----------|-------------|---------------------------|----------------------| +| GV-1 | 策略 | AI-GOVERNANCE-POLICY.md、DOCUMENTATION-POLICY.md | 完整文档 | +| GV-2 | 问责 | AGENT-RULES.md、AI-GOVERNANCE-POLICY.md | 自主权表、第 2.2 节 | +| GV-3 | 劳动力多样性 | AI-GOVERNANCE-POLICY.md | 第 4 节 | +| GV-4 | 组织文化 | PRINCIPLES.md | 核心原则 | +| GV-5 | 利益相关者参与 | MANAGEMENT-REVIEW-TEMPLATE.md | 反馈摘要、行动项 | +| GV-6 | 供应链 | SBOM | 完整文档 | + +--- + +*NIST AI RMF GOVERN 功能实施指南 --- StrayMark Framework* + + diff --git a/.straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-MANAGE-GUIDE.md b/.straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-MANAGE-GUIDE.md new file mode 100644 index 0000000..4593690 --- /dev/null +++ b/.straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-MANAGE-GUIDE.md @@ -0,0 +1,123 @@ +# NIST AI RMF --- MANAGE 功能实施指南 + +> **框架**: NIST AI Risk Management Framework (AI RMF 1.0) +> **功能**: MANAGE --- 风险应对、缓解和监控 +> +> MANAGE 功能分配资源并实施计划，以持续应对、缓解和监控 AI 风险。它将风险评估转化为减少危害并在 AI 系统生命周期内维护可信度的具体行动。 + +--- + +## MG-1: 风险应对 + +规划和执行对已识别风险的应对措施。风险应对包括接受、规避、转移或缓解，每项都需记录明确的理由和问责。 + +> 每个已识别的风险都必须有明确的应对策略。未记录的风险接受等同于隐性疏忽。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 风险应对决策 | ADR | 决策与理由部分 | +| 建议的缓解措施 | ETH | 建议部分 | +| 架构层面的缓解 | ADR | 后果部分 | +| 应对优先级 | AI-RISK-CATALOG.md | 优先级、状态列 | +| 决策理由 | AIDEC | 备选方案考量、决策部分 | + +### 实施检查清单 + +- [ ] 为 AI-RISK-CATALOG.md 中的每项风险记录选定的应对策略（接受、规避、转移、缓解） +- [ ] 为缓解高严重性风险所做的架构决策创建 ADR +- [ ] 在 ETH 建议部分记录缓解建议 +- [ ] 为每项风险应对行动指定负责人和截止日期 + +--- + +## MG-2: 风险缓解 + +实施具体的技术和组织控制措施以降低风险严重性或发生可能性。验证缓解措施是否有效且不会引入新的风险。 + +> 缓解措施必须经过验证，而非假设有效。实施控制措施、测试它们，并记录其有效性的证据。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 安全控制 | SEC | 已实施控制部分 | +| 隐私缓解措施 | DPIA | 缓解措施部分 | +| 偏见缓解措施 | ETH | 偏见评估、建议部分 | +| 技术保障措施 | ADR | 实施细节部分 | +| 缓解措施测试 | TES | 缓解措施验证测试 | + +### 实施检查清单 + +- [ ] 在 SEC 文档中记录已实施的安全控制，并引用其所解决的风险 +- [ ] 为每个已识别的隐私风险完成 DPIA 缓解措施部分 +- [ ] 创建专门验证关键缓解措施有效性的 TES 文档 +- [ ] 在缓解措施部署和验证后，更新 AI-RISK-CATALOG.md 中的残余风险等级 + +--- + +## MG-3: 第三方风险管理 + +管理因第三方 AI 组件、模型、数据源、API 和服务而产生的风险。确保供应链透明度并建立合同保护。 + +> 第三方组件会继承和传播风险。组织对其供应商引入的风险仍须承担责任。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 第三方清单 | SBOM | 第三方服务、组件部分 | +| 组件风险评估 | SBOM | 风险评估部分 | +| 供应链透明度 | SBOM | 许可证、版本、来源列 | +| 供应商评估 | ETH | 第三方风险部分 | +| 依赖项跟踪 | SBOM | 依赖项部分 | + +### 实施检查清单 + +- [ ] 维护列出所有第三方 AI 组件、模型和数据源的最新 SBOM +- [ ] 评估每个第三方组件的风险并记录在 SBOM 风险评估部分 +- [ ] 当关键供应商的组件影响高风险功能时，通过专门的 ETH 文档进行评估 +- [ ] 建立第三方组件的审查周期并在 SBOM 中记录审查日期 + +--- + +## MG-4: 部署后监控 + +监控已部署的 AI 系统的性能退化、新出现的风险、事件和运行环境的变化。在整个系统生命周期内保持运营感知。 + +> 部署不是风险管理的终点——而是现实世界风险开始显现的起点。持续监控至关重要。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 事件跟踪 | INC | 完整文档 | +| 生命周期状态 | AI-LIFECYCLE-TRACKER.md | 监控阶段部分 | +| 运营监控 | AILOG | 监控和可观测性条目 | +| 性能漂移检测 | TES | 回归和漂移测试 | +| 系统健康 | `straymark status` | 文档健康指标 | + +### 实施检查清单 + +- [ ] 为每个运营事件创建 INC 文档，包含严重性分类和时间线 +- [ ] 在 AI-LIFECYCLE-TRACKER.md 中跟踪系统的生命周期阶段，并随系统演进进行更新 +- [ ] 在 AILOG 条目中记录与监控相关的变更和观察结果 +- [ ] 定期运行回归测试（TES）以检测已部署系统的性能漂移 + +--- + +## 摘要：MANAGE 功能到 StrayMark 映射 + +| 类别 | 描述 | 主要 StrayMark 文档 | 关键字段 / 部分 | +|----------|-------------|---------------------------|----------------------| +| MG-1 | 风险应对 | ETH、ADR | 建议、决策与理由 | +| MG-2 | 风险缓解 | SEC、DPIA | 已实施控制、缓解措施 | +| MG-3 | 第三方风险 | SBOM | 第三方服务、风险评估 | +| MG-4 | 部署后监控 | INC、AI-LIFECYCLE-TRACKER.md | 完整文档、监控阶段 | + +--- + +*NIST AI RMF MANAGE 功能实施指南 --- StrayMark Framework* + + diff --git a/.straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-MAP-GUIDE.md b/.straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-MAP-GUIDE.md new file mode 100644 index 0000000..ea129e5 --- /dev/null +++ b/.straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-MAP-GUIDE.md @@ -0,0 +1,150 @@ +# NIST AI RMF --- MAP 功能实施指南 + +> **框架**: NIST AI Risk Management Framework (AI RMF 1.0) +> **功能**: MAP --- 上下文、分类和风险识别 +> +> MAP 功能为 AI 系统建立上下文，识别和分类风险，并评估对个人、组织和社会的潜在影响。它是所有后续风险管理活动的基础。 + +--- + +## MP-1: 上下文建立 + +记录 AI 系统的目的、运行环境、利益相关者和预期领域。上下文是识别相关风险的基础。 + +> 建立详尽的上下文确保风险评估基于系统的实际部署条件，而非通用假设。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 系统目的和范围 | AILOG | `title`、摘要部分 | +| 运行环境 | AILOG | 上下文部分 | +| 利益相关者和用户 | ETH | 利益相关者分析部分 | +| 法规环境 | MCARD | `regulatory_frameworks`、法规合规部分 | +| 部署约束 | ADR | 上下文与约束部分 | + +### 实施检查清单 + +- [ ] 创建 AILOG 条目，记录 AI 系统的目的、范围和运行上下文 +- [ ] 在 ETH 文档中识别所有利益相关者（用户、受影响方、操作员） +- [ ] 在 MCARD 中记录法规环境和适用的框架 +- [ ] 在 ADR 中记录部署约束和假设条件 + +--- + +## MP-2: 分类和风险分级 + +根据 AI 系统的预期用途、潜在危害以及运行领域的敏感程度对其进行风险等级分类。 + +> 风险分类决定了文档和审查要求的深度。高风险系统需要更严格的证据。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 风险等级分类 | ETH | `risk_level`（low / medium / high / critical） | +| EU AI Act 风险等级 | ETH | `eu_ai_act_risk`（minimal / limited / high / unacceptable） | +| 生成式 AI 特定风险 | ETH | `nist_genai_risks` 数组 | +| 领域敏感度 | MCARD | `intended_use`、领域部分 | +| 系统分类理由 | ADR | 决策与理由部分 | + +### 实施检查清单 + +- [ ] 根据潜在危害在 ETH frontmatter 中分配 `risk_level` +- [ ] 使用 `eu_ai_act_risk` 字段将系统映射到 EU AI Act 风险等级 +- [ ] 在 `nist_genai_risks` 中识别适用的生成式 AI 风险类别（参见 NIST-AI-600-1-GENAI-RISKS.md） +- [ ] 如果风险等级存在争议或不明显，在 ADR 中记录所选分类的理由 + +--- + +## MP-3: AI 能力与局限性 + +记录 AI 系统的预期能力及其已知局限性、故障模式和性能退化的条件。 + +> 对局限性的透明记录可防止过度依赖，并支持操作员和用户做出知情决策。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 预期用途和能力 | MCARD | 预期用途部分、`intended_use` | +| 已知局限性 | MCARD | 局限性部分 | +| 性能边界 | MCARD | 性能指标部分 | +| 故障模式 | TES | 边缘情况和故障测试部分 | +| 超出范围的用途 | MCARD | 超出范围的用途部分 | + +### 实施检查清单 + +- [ ] 完成 MCARD 预期用途部分，明确说明系统的设计用途 +- [ ] 在 MCARD 局限性部分记录所有已知的局限性和故障条件 +- [ ] 在 MCARD 性能指标中定义性能边界和退化条件 +- [ ] 创建 TES 文档以验证边界条件和对抗性条件下的行为 + +--- + +## MP-4: 风险映射与注册 + +维护一个集中的已识别风险注册表，包括其严重性、可能性、当前控制措施和责任负责人。 + +> 动态的风险注册表确保风险随时间持续跟踪，而非仅被识别一次后就被遗忘。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 风险目录 | AI-RISK-CATALOG.md | 完整文档 | +| 单项风险评估 | ETH | 风险评估部分 | +| 风险严重性和可能性 | AI-RISK-CATALOG.md | 严重性、可能性列 | +| 风险负责人 | AI-RISK-CATALOG.md | 负责人列 | +| 缓解状态 | AI-RISK-CATALOG.md | 状态、当前控制措施列 | + +### 实施检查清单 + +- [ ] 创建或更新 AI-RISK-CATALOG.md，纳入所有已识别的风险 +- [ ] 将每个风险条目链接到提供详细评估的相应 ETH 文档 +- [ ] 为每个已编目的风险指定负责人和审查日期 +- [ ] 使用 `straymark compliance` 安排定期审查以验证风险目录的时效性 + +--- + +## MP-5: 影响评估 + +评估 AI 系统对个人（权利、安全、福祉）、群体（公平、偏见）、社区、环境和组织的潜在影响。 + +> 影响评估必须同时考虑预期效果和合理可预见的意外后果，涵盖所有受影响方。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 个人权利影响 | DPIA | 权利影响评估部分 | +| 偏见和公平影响 | ETH | 偏见评估部分 | +| 环境影响 | ETH | 环境影响部分 | +| 社会影响 | ETH | 社会影响部分 | +| 组织影响 | ETH | 风险评估部分 | +| 数据保护影响 | DPIA | 完整文档 | + +### 实施检查清单 + +- [ ] 为处理个人数据或影响个人权利的系统完成 DPIA +- [ ] 在 ETH 偏见评估部分评估偏见和公平性影响 +- [ ] 在 ETH 环境影响部分评估环境成本（计算、能源、碳排放） +- [ ] 记录社会和社区影响，特别是大规模部署的系统 + +--- + +## 摘要：MAP 功能到 StrayMark 映射 + +| 类别 | 描述 | 主要 StrayMark 文档 | 关键字段 / 部分 | +|----------|-------------|---------------------------|----------------------| +| MP-1 | 上下文建立 | AILOG、ETH | 上下文部分、利益相关者分析 | +| MP-2 | 分类 | ETH | `risk_level`、`eu_ai_act_risk`、`nist_genai_risks` | +| MP-3 | AI 能力 | MCARD | 预期用途、局限性、性能指标 | +| MP-4 | 风险映射 | AI-RISK-CATALOG.md | 严重性、可能性、负责人、状态 | +| MP-5 | 影响评估 | DPIA、ETH | 权利影响、偏见评估、环境影响 | + +--- + +*NIST AI RMF MAP 功能实施指南 --- StrayMark Framework* + + diff --git a/.straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-MEASURE-GUIDE.md b/.straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-MEASURE-GUIDE.md new file mode 100644 index 0000000..6c1a823 --- /dev/null +++ b/.straymark/03-implementation/i18n/zh-CN/NIST-AI-RMF-MEASURE-GUIDE.md @@ -0,0 +1,125 @@ +# NIST AI RMF --- MEASURE 功能实施指南 + +> **框架**: NIST AI Risk Management Framework (AI RMF 1.0) +> **功能**: MEASURE --- 定量和定性风险评估 +> +> MEASURE 功能采用定量和定性方法来分析、评估、基准测试和监控 AI 风险及其相关影响。它为知情的风险管理决策提供证据基础。 + +--- + +## MS-1: 指标识别 + +定义评估 AI 系统性能、可信度和风险的适当指标。指标应可测量、与系统上下文相关，并与组织目标一致。 + +> 好的指标是具体的、可一致测量的，并且与系统相关的风险和可信度特征直接挂钩。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| KPI 定义 | AI-KPIS.md | 完整文档 | +| 性能指标 | TES | 性能指标部分 | +| 准确性和可靠性指标 | MCARD | 性能指标部分 | +| 文档健康指标 | `straymark status` | 覆盖率、时效性、审查率 | +| 合规指标 | `straymark compliance` | 验证结果 | + +### 实施检查清单 + +- [ ] 在 AI-KPIS.md 中定义关键绩效指标，涵盖准确性、公平性、可靠性和安全性 +- [ ] 在 TES 文档中为每个指标建立基线测量值 +- [ ] 在 MCARD 性能指标部分为每个指标设定阈值和警报条件 +- [ ] 定期运行 `straymark status` 以将文档健康作为治理指标进行跟踪 + +--- + +## MS-2: 可信度评估 + +根据可信度特征评估 AI 系统：有效性、可靠性、安全性、信息安全、问责、透明度、可解释性、隐私和公平性。 + +> 可信度是多维的。一个系统可能在准确性上表现出色，但在公平性或透明度上存在不足。评估必须涵盖所有相关维度。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 偏见和公平性评估 | ETH | 偏见评估部分 | +| 透明度评估 | ETH | 透明度部分 | +| 可解释性评估 | ETH | 可解释性部分 | +| 隐私评估 | ETH | 数据隐私部分、DPIA | +| 性能验证 | MCARD | 性能指标部分 | +| 安全评估 | SEC | 完整文档 | +| 安全性评估 | ETH | 风险评估部分 | + +### 实施检查清单 + +- [ ] 完成 ETH 偏见评估部分，尽可能包含定量公平性指标 +- [ ] 记录系统的透明度特征，包括向用户和操作员提供了哪些信息 +- [ ] 评估可解释性：系统的输出是否可以被人类理解和审计？ +- [ ] 通过具有可重现测试结果的 TES 文档验证性能声明 + +--- + +## MS-3: 风险跟踪 + +随时间跟踪已识别的风险，监控严重性、可能性的变化以及缓解控制措施的有效性。维护风险演变的可审计记录。 + +> 风险跟踪将静态的风险注册表转变为反映实际系统行为和变化条件的动态治理工具。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 风险状态变化 | AI-RISK-CATALOG.md | 审查日期、状态列 | +| 合规验证 | `straymark compliance` | 验证输出 | +| 风险等级变更 | ETH | `risk_level` 字段（跨版本跟踪） | +| 控制有效性 | AI-RISK-CATALOG.md | 当前控制措施、残余风险列 | +| 趋势分析 | AI-KPIS.md | 趋势指标部分 | + +### 实施检查清单 + +- [ ] 为 AI-RISK-CATALOG.md 中的每个条目设定审查日期并按期执行 +- [ ] 将 `straymark compliance` 作为 CI 的一部分运行，以检测文档空白和过时的风险评估 +- [ ] 当新证据改变风险概况时更新 ETH 的 `risk_level` 字段 +- [ ] 在每个风险审查周期中记录控制有效性的观察结果 + +--- + +## MS-4: 反馈整合 + +将来自用户、操作员、事件报告和监控数据的反馈纳入风险评估流程。利用这些证据来优化指标和更新风险评估。 + +> 反馈闭环弥合了理论风险评估与观察到的实际行为之间的差距。没有反馈闭环，风险管理就会脱离现实。 + +### StrayMark 映射 + +| NIST 要求 | StrayMark 文档 | 部分 / 字段 | +|------------------|-------------------|-----------------| +| 事件事后分析 | INC | 事后分析部分 | +| 用户反馈整合 | MANAGEMENT-REVIEW-TEMPLATE.md | 反馈摘要部分 | +| 监控数据 | AILOG | 监控和可观测性条目 | +| 经验教训 | INC | 经验教训部分 | +| 审查行动 | MANAGEMENT-REVIEW-TEMPLATE.md | 行动项部分 | + +### 实施检查清单 + +- [ ] 为每个重大事件创建 INC 文档，包含根本原因分析和经验教训 +- [ ] 将事件发现反馈到 AI-RISK-CATALOG.md 中以更新风险严重性和控制措施 +- [ ] 使用 MANAGEMENT-REVIEW-TEMPLATE.md 构建整合所有反馈来源的定期审查 +- [ ] 当监控发现新的故障模式时，更新 ETH 文档和 MCARD 局限性 + +--- + +## 摘要：MEASURE 功能到 StrayMark 映射 + +| 类别 | 描述 | 主要 StrayMark 文档 | 关键字段 / 部分 | +|----------|-------------|---------------------------|----------------------| +| MS-1 | 指标识别 | AI-KPIS.md、TES | KPI 定义、性能指标 | +| MS-2 | 可信度评估 | ETH、MCARD | 偏见评估、性能指标 | +| MS-3 | 风险跟踪 | AI-RISK-CATALOG.md | 审查日期、状态、`straymark compliance` | +| MS-4 | 反馈整合 | INC、MANAGEMENT-REVIEW-TEMPLATE.md | 事后分析、行动项 | + +--- + +*NIST AI RMF MEASURE 功能实施指南 --- StrayMark Framework* + + diff --git a/.devtrail/04-testing/.gitkeep b/.straymark/04-testing/.gitkeep similarity index 100% rename from .devtrail/04-testing/.gitkeep rename to .straymark/04-testing/.gitkeep diff --git a/.devtrail/04-testing/TES-2026-04-03-001-cli-integration-test-coverage.md b/.straymark/04-testing/TES-2026-04-03-001-cli-integration-test-coverage.md similarity index 100% rename from .devtrail/04-testing/TES-2026-04-03-001-cli-integration-test-coverage.md rename to .straymark/04-testing/TES-2026-04-03-001-cli-integration-test-coverage.md diff --git a/.devtrail/05-operations/incidents/.gitkeep b/.straymark/05-operations/incidents/.gitkeep similarity index 100% rename from .devtrail/05-operations/incidents/.gitkeep rename to .straymark/05-operations/incidents/.gitkeep diff --git a/.devtrail/05-operations/runbooks/.gitkeep b/.straymark/05-operations/runbooks/.gitkeep similarity index 100% rename from .devtrail/05-operations/runbooks/.gitkeep rename to .straymark/05-operations/runbooks/.gitkeep diff --git a/.devtrail/06-evolution/technical-debt/.gitkeep b/.straymark/06-evolution/technical-debt/.gitkeep similarity index 100% rename from .devtrail/06-evolution/technical-debt/.gitkeep rename to .straymark/06-evolution/technical-debt/.gitkeep diff --git a/.devtrail/07-ai-audit/SBOM-2026-04-03-001-self-update-dependency.md b/.straymark/07-ai-audit/SBOM-2026-04-03-001-self-update-dependency.md similarity index 100% rename from .devtrail/07-ai-audit/SBOM-2026-04-03-001-self-update-dependency.md rename to .straymark/07-ai-audit/SBOM-2026-04-03-001-self-update-dependency.md diff --git a/.devtrail/07-ai-audit/agent-logs/.gitkeep b/.straymark/07-ai-audit/agent-logs/.gitkeep similarity index 100% rename from .devtrail/07-ai-audit/agent-logs/.gitkeep rename to .straymark/07-ai-audit/agent-logs/.gitkeep diff --git a/.devtrail/07-ai-audit/agent-logs/AILOG-2026-04-02-001-add-git-operations-rules-claude-md.md b/.straymark/07-ai-audit/agent-logs/AILOG-2026-04-02-001-add-git-operations-rules-claude-md.md similarity index 100% rename from .devtrail/07-ai-audit/agent-logs/AILOG-2026-04-02-001-add-git-operations-rules-claude-md.md rename to .straymark/07-ai-audit/agent-logs/AILOG-2026-04-02-001-add-git-operations-rules-claude-md.md diff --git a/.devtrail/07-ai-audit/agent-logs/AILOG-2026-04-02-002-implement-core-cli-mvp.md b/.straymark/07-ai-audit/agent-logs/AILOG-2026-04-02-002-implement-core-cli-mvp.md similarity index 100% rename from .devtrail/07-ai-audit/agent-logs/AILOG-2026-04-02-002-implement-core-cli-mvp.md rename to .straymark/07-ai-audit/agent-logs/AILOG-2026-04-02-002-implement-core-cli-mvp.md diff --git a/.devtrail/07-ai-audit/agent-logs/AILOG-2026-04-03-001-add-integration-test-suite.md b/.straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-001-add-integration-test-suite.md similarity index 100% rename from .devtrail/07-ai-audit/agent-logs/AILOG-2026-04-03-001-add-integration-test-suite.md rename to .straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-001-add-integration-test-suite.md diff --git a/.devtrail/07-ai-audit/agent-logs/AILOG-2026-04-03-002-ci-workflow-and-crates-metadata.md b/.straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-002-ci-workflow-and-crates-metadata.md similarity index 100% rename from .devtrail/07-ai-audit/agent-logs/AILOG-2026-04-03-002-ci-workflow-and-crates-metadata.md rename to .straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-002-ci-workflow-and-crates-metadata.md diff --git a/.devtrail/07-ai-audit/agent-logs/AILOG-2026-04-03-003-cargo-dist-release-infrastructure.md b/.straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-003-cargo-dist-release-infrastructure.md similarity index 100% rename from .devtrail/07-ai-audit/agent-logs/AILOG-2026-04-03-003-cargo-dist-release-infrastructure.md rename to .straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-003-cargo-dist-release-infrastructure.md diff --git a/.devtrail/07-ai-audit/agent-logs/AILOG-2026-04-03-004-update-subcommand.md b/.straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-004-update-subcommand.md similarity index 100% rename from .devtrail/07-ai-audit/agent-logs/AILOG-2026-04-03-004-update-subcommand.md rename to .straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-004-update-subcommand.md diff --git a/.devtrail/07-ai-audit/agent-logs/AILOG-2026-04-03-005-fix-binary-name.md b/.straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-005-fix-binary-name.md similarity index 100% rename from .devtrail/07-ai-audit/agent-logs/AILOG-2026-04-03-005-fix-binary-name.md rename to .straymark/07-ai-audit/agent-logs/AILOG-2026-04-03-005-fix-binary-name.md diff --git a/.devtrail/07-ai-audit/agent-logs/AILOG-2026-04-04-001-about-subcommand.md b/.straymark/07-ai-audit/agent-logs/AILOG-2026-04-04-001-about-subcommand.md similarity index 100% rename from .devtrail/07-ai-audit/agent-logs/AILOG-2026-04-04-001-about-subcommand.md rename to .straymark/07-ai-audit/agent-logs/AILOG-2026-04-04-001-about-subcommand.md diff --git a/.straymark/07-ai-audit/agent-logs/AILOG-2026-05-19-001-rebrand-devtrail-to-straymark.md b/.straymark/07-ai-audit/agent-logs/AILOG-2026-05-19-001-rebrand-devtrail-to-straymark.md new file mode 100644 index 0000000..0138ae6 --- /dev/null +++ b/.straymark/07-ai-audit/agent-logs/AILOG-2026-05-19-001-rebrand-devtrail-to-straymark.md @@ -0,0 +1,103 @@ +--- +id: AILOG-2026-05-19-001 +title: Rebrand DevTrail → StrayMark and migrate framework to fw-4.17.0 +status: accepted +created: 2026-05-19 +agent: claude-code-v4.7 +confidence: high +review_required: true +risk_level: medium +eu_ai_act_risk: not_applicable +nist_genai_risks: [] +iso_42001_clause: [7, 8] +lines_changed: 0 +files_modified: + - .devtrail/ (renamed → .straymark/) + - CLAUDE.md + - .cursorrules + - Cargo.toml + - GEMINI.md + - .github/copilot-instructions.md + - .specify/memory/constitution.md + - .specify/starter/IDEA.md + - DEVTRAIL.md (deleted; STRAYMARK.md installed by framework) + - .claude/skills/devtrail-* (7 deleted) + - .gemini/skills/devtrail-* (7 deleted) + - .agent/workflows/devtrail-*.md (7 deleted) + - .cursor/rules/devtrail.md (deleted) +observability_scope: none +tags: [rebrand, straymark, framework-update, governance, tooling] +related: + - AILOG-2026-04-02-001-add-git-operations-rules-claude-md.md +--- + +# AILOG: Rebrand DevTrail → StrayMark and migrate framework to fw-4.17.0 + +## Summary + +Upstream DevTrail tool was renamed to **StrayMark**. This change migrates the arborist-cli repo from the DevTrail framework (fw-4.1.0, CLI v3.15.0 as `devtrail`) to the StrayMark framework (fw-4.17.0, CLI v3.15.0 as `straymark`): the `.devtrail/` directory was renamed to `.straymark/`, the framework was repaired and updated, orphan `devtrail-*` files were removed, and project-level references in directive files (`CLAUDE.md`, `.cursorrules`, `Cargo.toml`, `.specify/*`) were updated. No code in `src/` was touched. + +## Context + +The `straymark` CLI is now installed at `~/.cargo/bin/straymark` (v3.15.0). Running `straymark status` against the repo reported `StrayMark is not installed` because the tool looks for `.straymark/`, not `.devtrail/`. Beyond the simple rename, the new framework version (fw-4.17.0) introduces new concepts not present in fw-4.1.0: **Charters** (bounded units of work with telemetry), GB 45438 AI content labeling, multi-batch ledgers, external audit pipelines, China regulatory scope (opt-in), and additional `.straymark/00-governance/` files (CHARTER-CHAIN-EVOLUTION, EMERGENT-OBSERVATION-DESIGN, FOLLOW-UPS-BACKLOG-PATTERN, SPECKIT-CHARTER-BRIDGE, CHINA-REGULATORY-FRAMEWORK, etc.). The operator chose to bundle the rebrand and the framework upgrade in a single PR rather than land them sequentially. + +Before starting, two untracked artifacts (`dist-manifest.yml` in repo root and `dist-templates/`) were identified as residue from a prior DevTrail experiment and discarded per operator decision. + +## Actions Performed + +1. Created branch `feat/straymark-rebrand` from `main`. +2. Deleted untracked residuals `dist-manifest.yml` (root) and `dist-templates/`. +3. `git stash`'d 16 locally-modified framework files; later inspected the stash, confirmed the only substantive change (cognitive-complexity heuristic in `devtrail-status` skills) was already incorporated upstream in fw-4.17.0, and dropped the stash. +4. `git mv .devtrail .straymark` — preserves git history for all 81+ framework files. +5. Ran `straymark repair` — framework auto-detected the rename, downloaded fw-4.17.0, restored 117 files including `STRAYMARK.md`, schemas, charter templates, China-regulatory artifacts, zh-CN translations, `AGENTS.md`, and rebrandend skills/workflows (`.claude/skills/straymark-*`, `.gemini/skills/straymark-*`, `.agent/workflows/straymark-*`, `.cursor/rules/straymark.md`). +6. Ran `straymark update-framework` — updated 190 files from fw-4.1.0 to fw-4.17.0; the new ` ... ` directive block was injected into `CLAUDE.md` and `.cursorrules`. +7. Deleted orphan files: `DEVTRAIL.md`, 7× `.claude/skills/devtrail-*/`, 7× `.gemini/skills/devtrail-*/`, 7× `.agent/workflows/devtrail-*.md`, `.cursor/rules/devtrail.md`. +8. Manually rewrote `CLAUDE.md` and `.cursorrules` to remove the legacy ` ... ` block left behind by the framework update and replace the project's header strings (`DevTrail` → `StrayMark`, `.devtrail/` → `.straymark/`, `devtrail analyze` → `straymark analyze`). +9. Updated `Cargo.toml` `exclude` to point at `.straymark/`. +10. Deleted stale `GEMINI.md` and `.github/copilot-instructions.md` (still carrying the legacy block) and re-ran `straymark repair`, which regenerated them from the new manifest. +11. Updated project-level references in `.specify/memory/constitution.md` and `.specify/starter/IDEA.md` (kept one explicit "formerly DevTrail" mention as historical context). +12. Validated: `cargo check` (clean), `cargo test` (29/29 pass), `straymark validate` (0 errors, 1 preexisting unrelated warning), `straymark status` (framework fw-4.17.0, CLI cli-3.15.0, 17/17 structure items OK). +13. Updated Claude's auto-memory (`MEMORY.md`, renamed `feedback_devtrail_complexity.md` → `feedback_straymark_complexity.md`, edited `feedback_git_workflow.md`, added `project_rebrand_straymark.md`). + +## Modified Files + +| File | Lines Changed (+/-) | Change Description | +|------|--------------------|--------------------| +| `.devtrail/` → `.straymark/` | n/a | Directory rename (`git mv`); preserves history. | +| `CLAUDE.md` | rewritten | Removed legacy block, `DevTrail`→`StrayMark`, path updates. | +| `.cursorrules` | rewritten | Same as above. | +| `Cargo.toml` | 1 line | `exclude` path. | +| `Cargo.lock` | 0 | No dependency change. | +| `STRAYMARK.md` | created | Installed by framework (replaces `DEVTRAIL.md`). | +| `AGENTS.md` | created | New open-standard directive file introduced in fw-4.17.0. | +| `.claude/skills/straymark-*` | 11 created | New skills (adr, aidec, ailog, audit-execute, audit-prompt, audit-review, charter-new, mcard, new, sec, status). | +| `.gemini/skills/straymark-*` | 11 created | Same. | +| `.agent/workflows/straymark-*.md` | 11 created | Same. | +| `.cursor/rules/straymark.md` | created | New directive injection target. | +| `.straymark/schemas/*` | 3 created | Charter telemetry/audit schemas. | +| `.straymark/00-governance/*` (new) | 12 created | Charter, China, observation-design files. | +| `.devtrail/**` orphans | 7+7+7+5 deleted | DEVTRAIL.md + devtrail-* skills/workflows/rules. | +| `.specify/memory/constitution.md` | 2 lines | `DevTrail`→`StrayMark`. | +| `.specify/starter/IDEA.md` | 3 lines | Same + "formerly DevTrail" historical clarifier. | + +## Decisions & Tradeoffs + +- **Bundled rebrand + framework update in one PR.** Alternative: split into rebrand-only commit followed by update-framework commit. Chose the bundle because (a) `straymark repair` and `update-framework` together regenerate the new content in one pass, (b) the operator already confirmed scope. Commit history within the branch is still segmented by phase. +- **Did not edit historical AILOGs/TES/AIDEC/SBOM** under `.straymark/07-ai-audit/` and `.straymark/04-testing/` even though they mention "DevTrail". These are point-in-time records and should remain faithful to the naming at the time of writing. +- **Discarded stash entirely** after confirming its substantive content (cognitive-complexity heuristic) is already upstream in fw-4.17.0. Avoided manual conflict resolution against renamed paths. +- **Kept one "formerly DevTrail" mention** in `.specify/starter/IDEA.md` to preserve the project's origin story. + +## Verification + +- `cargo check` — clean. +- `cargo test` — 29 passed, 0 failed. +- `straymark status` — Framework fw-4.17.0, CLI cli-3.15.0, all 17 structure items OK. +- `straymark validate` — 0 errors, 1 preexisting warning unrelated to rebrand (`AILOG-2026-04-04-001-about-subcommand.md` has no traceability links — predates this AILOG). +- `grep -r "devtrail\|DevTrail"` over tracked non-historical files — only the intentional "formerly DevTrail" clarifier in `.specify/starter/IDEA.md` remains. + +## Risks & Follow-ups + +- **risk_level: medium** because the change touches every directive file an AI agent reads when entering this repo. A mis-edit could cause future agents to misroute documents or look for nonexistent paths. Mitigated by `straymark validate` and the cargo test suite, but a human review is recommended (`review_required: true`). +- New Charter machinery (`.straymark/charters/`, `straymark charter new`) is now available but not adopted by any in-flight work. Future sessions can opt in. +- China regulatory scope is **not** enabled (`.straymark/config.yml` `regional_scope` unset). The China-specific templates and governance files are present but inert. +- No follow-up issues required; rebrand is self-contained. diff --git a/.devtrail/07-ai-audit/decisions/.gitkeep b/.straymark/07-ai-audit/decisions/.gitkeep similarity index 100% rename from .devtrail/07-ai-audit/decisions/.gitkeep rename to .straymark/07-ai-audit/decisions/.gitkeep diff --git a/.devtrail/07-ai-audit/decisions/AIDEC-2026-04-03-001-cli-restructure-and-self-update-strategy.md b/.straymark/07-ai-audit/decisions/AIDEC-2026-04-03-001-cli-restructure-and-self-update-strategy.md similarity index 100% rename from .devtrail/07-ai-audit/decisions/AIDEC-2026-04-03-001-cli-restructure-and-self-update-strategy.md rename to .straymark/07-ai-audit/decisions/AIDEC-2026-04-03-001-cli-restructure-and-self-update-strategy.md diff --git a/.devtrail/07-ai-audit/ethical-reviews/.gitkeep b/.straymark/07-ai-audit/ethical-reviews/.gitkeep similarity index 100% rename from .devtrail/07-ai-audit/ethical-reviews/.gitkeep rename to .straymark/07-ai-audit/ethical-reviews/.gitkeep diff --git a/.devtrail/08-security/.gitkeep b/.straymark/08-security/.gitkeep similarity index 100% rename from .devtrail/08-security/.gitkeep rename to .straymark/08-security/.gitkeep diff --git a/.devtrail/09-ai-models/.gitkeep b/.straymark/09-ai-models/.gitkeep similarity index 100% rename from .devtrail/09-ai-models/.gitkeep rename to .straymark/09-ai-models/.gitkeep diff --git a/.devtrail/QUICK-REFERENCE.md b/.straymark/QUICK-REFERENCE.md similarity index 85% rename from .devtrail/QUICK-REFERENCE.md rename to .straymark/QUICK-REFERENCE.md index 2dab943..20f8cfb 100644 --- a/.devtrail/QUICK-REFERENCE.md +++ b/.straymark/QUICK-REFERENCE.md @@ -1,4 +1,4 @@ -# DevTrail - Quick Reference +# StrayMark - Quick Reference > One-page reference for AI agents and developers. > @@ -9,7 +9,7 @@ ## Language Configuration -**File**: `.devtrail/config.yml` +**File**: `.straymark/config.yml` ```yaml language: en # Options: en, es (default: en) @@ -17,8 +17,8 @@ language: en # Options: en, es (default: en) | Language | Template Path | |----------|---------------| -| `en` | `.devtrail/templates/TEMPLATE-*.md` | -| `es` | `.devtrail/templates/i18n/es/TEMPLATE-*.md` | +| `en` | `.straymark/templates/TEMPLATE-*.md` | +| `es` | `.straymark/templates/i18n/es/TEMPLATE-*.md` | --- @@ -94,7 +94,7 @@ Mark `review_required: true` when: ## Folder Structure ``` -.devtrail/ +.straymark/ ├── 00-governance/ ← Policies ├── 01-requirements/ ← REQ ├── 02-design/decisions/ ← ADR @@ -148,11 +148,11 @@ Mark `review_required: true` when: | Command | Purpose | |---------|---------| -| `/devtrail-status` | Check documentation status and compliance | -| `/devtrail-new` | Create any document type (AI suggests) | -| `/devtrail-ailog` | Quick AILOG creation | -| `/devtrail-aidec` | Quick AIDEC creation | -| `/devtrail-adr` | Quick ADR creation | +| `/straymark-status` | Check documentation status and compliance | +| `/straymark-new` | Create any document type (AI suggests) | +| `/straymark-ailog` | Quick AILOG creation | +| `/straymark-aidec` | Quick AIDEC creation | +| `/straymark-adr` | Quick ADR creation | --- @@ -168,4 +168,4 @@ Mark `review_required: true` when: --- -*DevTrail v4.1.0 | [GitHub](https://github.com/StrangeDaysTech/devtrail) | [Strange Days Tech](https://strangedays.tech)* +*StrayMark fw-4.17.0 | [GitHub](https://github.com/StrangeDaysTech/straymark) | [Strange Days Tech](https://strangedays.tech)* diff --git a/.straymark/audit-prompts/audit-prompt.md b/.straymark/audit-prompts/audit-prompt.md new file mode 100644 index 0000000..e20934b --- /dev/null +++ b/.straymark/audit-prompts/audit-prompt.md @@ -0,0 +1,321 @@ + + +# Charter audit — `{{charter_id}}` + +## ⛔ ABSOLUTE RULE — READ-ONLY + +**Your only task is to AUDIT. You have no permission to modify ANY project file.** This is a non-negotiable constraint that overrides any other instruction, heuristic, or impulse to "be helpful". + +Specifically, you are FORBIDDEN from: + +- Editing, creating, renaming, or deleting source files. +- Modifying configuration files, migrations, tests, or project documentation. +- Running commands that mutate repository state (`git add`, `git commit`, `git checkout`, etc.). +- Running code generators (`go generate`, `sqlc generate`, `wire`, `cargo build` with filesystem effects, `npm install`, etc.). +- Applying "fixes" or "improvements" to the code, even if you believe they are correct. +- Reformatting, renaming, or reorganizing existing files. + +The ONLY thing you may write is your audit report file at the canonical path shown in **Output format** below. That is the ONLY file you have permission to create. + +If you find a bug, **DOCUMENT IT** in your report. Do NOT fix it. +If you find a missing file, **REPORT IT**. Do NOT create it. +If a test fails, **REPORT IT**. Do NOT repair it. + +**Violating this rule invalidates the entire audit.** + +--- + +## Your role + +You are an independent code auditor. Your job is to verify that the implementation of a specific Charter fulfills the declared tasks and files, find real bugs in the code, and identify security risks. **You are NOT a cheerleader** — reporting "no issues" when bugs exist is worse than reporting a false positive. + +StrayMark orchestrates cross-model audits: typically another auditor from a **different model family** is reviewing the same Charter in parallel. Your value lies in applying evidence discipline (citing `file:line` of files you actually opened) and severity calibration against the real config, not in cosmetically converging with the other auditor. + +--- + +## Project + +{{project_context}} + +*(The operator may fill this placeholder with a brief description of the project's stack and architecture if they want to give the auditor extra context. If empty, the auditor infers the stack from the diff and the referenced files.)* + +--- + +## STRICT scope + +**Charter under audit:** `{{charter_id}}` — {{charter_title}} +**Charter file:** `{{charter_path}}` +**Git range:** `{{git_range}}` + +The authoritative source of scope is the Charter file at `{{charter_path}}`. Read it in full before starting — it declares which files are modified, which tasks are executed, which risks are accepted, and what counts as successful closure. + +### Scope rules + +- Report only findings that touch **files or tasks declared in the Charter**, or that appear modified in the `git_range`. +- If you find a problem in code that belongs to another Charter (another unit of work), report it as **"Out-of-scope note"** in a separate section, NOT as a defect of this Charter. +- Do NOT report as defects: + - Modules not yet implemented that are planned for future Charters. + - Wiring / DI not connected when the wiring task belongs to another Charter. + - Missing integration tests when the test task belongs to another Charter. + - Files that do not exist but whose task is marked as `[ ]` (pending) in the Charter. + +### Originating AILOGs + +These AILOGs document the rationale and the emergent risks during execution. **Read them before auditing** — the `R` risks already documented there are NOT new findings, they are consciously accepted trade-offs. + +``` +{{ailog_paths}} +``` + +```markdown +{{ailog_contents}} +``` + +--- + +## Charter content + +```markdown +{{charter_content}} +``` + +--- + +## Diff + +```diff +{{git_diff}} +``` + +--- + +## What you must do + +### Step 1 — Read the scope + +Read the Charter file at `{{charter_path}}` in full. Identify: + +- The `## Tasks` section (or equivalent): each task, its description, and the expected file. +- The `## Files to modify` section: table of files and declared change type. +- The `## Risk` section or equivalent: `R` risks consciously accepted. +- The Charter's closure criterion (what makes it "complete"). + +### Step 2 — Verify each task (MANDATORY) + +For EACH task in the Charter, perform these steps in order: + +1. **Locate file(s)**: find the file mentioned in the task. If it does not exist, report as "Not found". If it exists, continue. +2. **Read the full implementation**: read the file entirely, not just the name. **Do not report "file exists" without reading its content.** +3. **Trace execution flow**: for key functions, follow the full chain (handler → service → repository → SQL/storage, or the equivalent in the project's stack). Verify that parameters propagate correctly through each layer. +4. **Verify tests**: locate the corresponding tests. Read at least 2 test cases to confirm they cover the happy path and at least one edge case. +5. **Compare against the task**: does the implementation match what the task describes? If there are discrepancies, report with evidence (`file:line`). + +> **Evidence discipline.** You may only opine on files you have opened via a tool call (Read, Grep, etc.). Any finding you produce must cite `file:line` of the specific files you opened. Findings without citations are treated as low confidence by the consolidated review and may be dropped. If you did not open a file, you cannot infer behavior, structure, or correctness about it. + +### Step 3 — Run verifications (when applicable) + +If your environment allows you to run project commands (build, lint, test), run them over the Charter's scope and report the output verbatim. **Read/verify commands only** — never generators or mutating commands. + +> *Stack examples* (adapt to the project you are auditing): +> - **Go**: `go vet ./...`, `go build ./...`, `go test .//... -v -count=1 2>&1 | tail -50` +> - **Rust**: `cargo check`, `cargo clippy --all-targets`, `cargo test --no-run` +> - **TypeScript/Node**: `npm run typecheck`, `npm run lint`, `npm test -- --run` +> - **Python**: `mypy `, `ruff check`, `pytest --co` + +If your environment does NOT allow command execution, skip this step and focus the audit on static reading of code + tests. + +### Step 4 — Evaluate Charter closure + +Read the closure criterion declared by the Charter. Assess: **is this criterion met by the current implementation?** The Charter's criterion is the source of truth for "complete or not", not your expectation of what it "should" include. + +### Step 5 — Calibrate severity against the project's REAL configuration + +Before assigning severity to EACH finding, verify the driver, flag, or configuration actually active in the code, NOT the theoretical worst case. + +**Rule:** severity must reflect the impact the finding has with the configuration the project uses TODAY, not the impact it would have under a hypothetical configuration. + +**Mandatory checks before declaring Critical or High severity:** + +- [ ] **Active driver**: if the finding concerns an event bus, cache, storage, queue, or any pluggable component, open the factory/config (typically something like `internal/core//factory.go`, `src//factory.ts`, `.env.example`, `config.yml`) and confirm which driver is actually instantiated. +- [ ] **Feature flags**: if the code has conditional branches keyed on an env var or flag, confirm the default value and the value used in the tests you validated. A bug that only triggers with `FEATURE_X=true` when the default is `false` is not Critical — it is conditional. +- [ ] **Build tags / conditional compilation**: if the code is behind `//go:build foo`, `#[cfg(feature = "foo")]`, `process.env.NODE_ENV !== 'production'`, etc., confirm whether that condition holds in the production build. Defects reproducible only under a dev or test tag are not production blockers. +- [ ] **DB role / user**: if the finding touches RLS, SQL permissions, or ACLs, verify under which role the app runs. (For example, the testcontainers superuser bypasses RLS; the production role may differ. Do not confuse test behavior with production behavior.) +- [ ] **Deployment scope**: if the finding concerns concurrency, distributed cache, or multi-instance coordination, confirm the configured scaling (`maxScale`, replicas, etc.). A race-condition bug between instances is not Critical if the deployment runs with `maxScale=1`. + +**How to classify when the finding is CONDITIONAL:** + +- **Critical / High**: the bug triggers under the configuration that runs TODAY in main or staging. +- **Medium / Low**: the bug is a real smell but has no operational trigger under the current config. +- **Post-Charter / non-blocking**: the bug is real and critical under a component that does not yet exist (e.g., an external service still stubbed), or under a flag explicitly disabled. Document it as a future concern with a clear note of "when" and "why" — NOT as a blocker for this Charter. + +**Anti-inflation rule:** you may not justify Critical severity by appealing solely to "the bug EXISTS in the code". You must demonstrate that **running** the application with its current configuration, the bug would actually manifest. If your justification begins with "if in the future X were implemented..." or "if someone enabled flag Y...", your severity must be post-Charter or Medium with a note, not Critical. + +**Anti-deflation rule:** conversely, you may not classify something as Low by appealing to "this never happens in practice" if the code has a clear path that triggers it under the current config. The absence of reported incidents is not evidence of the bug's absence. + +> **Example — declared deferral, not a defect.** Suppose Charter N introduces a thin in-memory adapter for a service the project plans to back with a real driver in a future Charter (call it Charter N+K). Charter N's `## Risk` section names the deferral explicitly (for example: *"R1: temporary in-memory adapter, replaced in CHARTER-N+K"*). If an auditor reading Charter N opens the component's factory and finds that the active driver is the in-memory adapter rather than the real implementation, they must **NOT** report this as a Critical finding — the deferral is declared scope, not hidden technical debt. Correct calibration requires opening the factory and verifying the active driver *before* declaring high severity; if the result matches a deferral declared in some Charter (this one or a previous one), the finding is at most *Post-Charter / non-blocking*. Conversely, if the same auditor finds another place where the same pattern was repeated **without** a declared deferral in any Charter, that **is** a finding (debt without an owner). + +--- + +## Finding categorization + +Each finding falls into one of these four categories. The consolidated review uses the same definitions: + +- **`hallucination`** — the Charter or the implementation references something that does not exist (an API, a function, a field, a behavior). The agent invented it. Verify by opening the actual file or API. +- **`implementation_gap`** — the Charter declared work the diff did not deliver, OR the diff delivered work the Charter did not declare, **without** being documented as a risk in the AILOG. (If it is documented in `## Risk` as `R` in some AILOG, that is NOT a gap — it is an accepted trade-off.) +- **`real_debt`** — a code-level concern that is correct with respect to the Charter but introduces technical debt or a subtle defect (a missing error path, a leaked resource, a non-idempotent operation). The adopter should capture this as a post-audit TDE doc. +- **`false_positive`** — what initially looked like a finding but, on closer inspection of the AILOG or the diff, is not. Document it anyway; the consolidated review uses these to recognize patterns where one auditor over-reports. + +--- + +## Output format + +Document your findings in a markdown file. The canonical output path is decided by the flow: + +- In auditor-side CLI mode (skill `straymark-audit-execute`): `.straymark/audits/{{charter_id}}/report-.md` (the skill handles the path automatically). +- In manual paste mode (transitional v0): the operator saves your output at `audit/charters/{{charter_id}}/auditor-{{audit_role}}.md` or an equivalent convention. + +The file must have this frontmatter (validated against `{{schema_path}}`): + +```yaml +--- +audit_role: auditor # v1 unified. Legacy v0: "auditor-primary" or "auditor-secondary" +auditor: # e.g., claude-sonnet-4-6, gemini-2.5-pro, copilot-v1.0.40 +charter_id: {{charter_id}} +git_range: "{{git_range}}" +prompt_used: +audited_at: +findings_total: +findings_by_category: + hallucination: + implementation_gap: + real_debt: + false_positive: +evidence_citations: # optional but recommended: how many file:line citations you made +audit_quality: high|medium|low # optional, self-assessment +--- + +# Audit: {{charter_id}} by + +## Executive summary + +[1-2 paragraphs: did execution match the Charter's declared scope? What is the overall verdict — clean, partial, drifted? What is the most material finding, if any?] + +## Compilation and test verification + +[Paste the output of the Step 3 commands here, if you ran them. If not, state "(skipped — no command execution available)".] + +## Task-by-task traceability + +For EACH task in the Charter, one entry with this format: + +### T### — [Task description] + +- **File(s)**: `path/to/file.ext:lines` +- **Status**: Implemented | Partial | Not implemented +- **Verification**: + - Implementation read: Yes/No + - Flow traced: [handler → service → repository → SQL] (or equivalent) + - Tests found: [test_file.ext, N test cases] +- **Findings**: [None | Description of the finding with `file:line`] + +## Findings + +Classified by severity. ONLY findings within the Charter's scope. + +### Critical (block Charter closure) + +| # | Finding | File:Line | Category | Evidence | Suggested remediation | +|---|---------|-----------|----------|----------|----------------------| + +### High (security or logic bugs) + +| # | Finding | File:Line | Category | Evidence | Suggested remediation | +|---|---------|-----------|----------|----------|----------------------| + +### Medium (inconsistencies, minor risks) + +| # | Finding | File:Line | Category | Evidence | Suggested remediation | +|---|---------|-----------|----------|----------|----------------------| + +### Low (quality, naming, style improvements) + +| # | Finding | File:Line | Category | Evidence | Suggested remediation | +|---|---------|-----------|----------|----------|----------------------| + +## Out-of-scope notes (optional) + +Observations about code that is NOT part of this Charter's scope but that you consider relevant to mention. These are NOT defects of this Charter. + +| Observation | Relevant Charter / area | Note | +|-------------|-------------------------|------| + +## Charter closure assessment + +Does the implementation meet the closure criterion declared by `{{charter_id}}`? +[Yes / No / Partial] — [Justification grounded in evidence, citing `file:line`] + +## Conclusion + +[2-3 sentences. Actual state of the Charter, critical findings if any, recommended next step.] +``` + +--- + +## What you must NOT do + +- **DO NOT MODIFY ANY PROJECT FILE.** Your only allowed output is the audit report. If you modify any other file, your audit will be discarded and considered invalid. This includes "fixing" bugs, "improving" code, creating missing files, or running generators. **REPORT, DO NOT ACT.** This is not optional or contextual — it is an absolute constraint. +- **DO NOT declare "no issues"** without having read the code of every task declared in the Charter. +- **DO NOT report tasks from other Charters** as defects of this one. +- **DO NOT inflate severity**: a finding from another Charter is not "Critical" here. +- **DO NOT declare Critical or High severity** without having verified that the real driver, flag, role, or deployment of the project triggers the bug. See Step 5. Declaring "critical regression" based on a stubbed component or a disabled flag invalidates the audit through false inflation. +- **DO NOT report** that a file "does not exist" without having searched with the correct path (including naming-convention variants used by the project). +- **DO NOT copy the file structure** without verifying content. +- **DO NOT ignore** the prior-audits folders (typically `audit/` or `.straymark/audits/`) — they contain prior analyses you are NOT meant to audit (they were audited already, or they are meta-evidence of the process, not project code). +- **DO NOT run** destructive or generative commands. Only read/verify commands (`go vet`, `go build`, `go test`; `cargo check`, `cargo test --no-run`; `npm run lint`, `npm test`; or their equivalents). +- **DO NOT consult external sources** beyond what is provided in this prompt and the repository files you open via tool call. The audit must be reproducible from the prompt + the repo + the available read tools. + +--- + +*StrayMark unified audit template v1. The seven universal sections (ABSOLUTE RULE, Your role, Scope rules, Step 2 mandatory verification, Step 5 severity calibration, What you must NOT do, Output format) come from the `audit/SKILL.md` skill mature pre-StrayMark in Sentinel, contributed via issue #102 by José Villaseñor Montfort (StrangeDaysTech). Sentinel-specific hardcodes (spec paths, Etapa headings, internal modules) were parameterized against the Charter doc, originating AILOGs, git range, and project context.* diff --git a/.straymark/audit-prompts/i18n/es/audit-prompt.md b/.straymark/audit-prompts/i18n/es/audit-prompt.md new file mode 100644 index 0000000..78ffb5e --- /dev/null +++ b/.straymark/audit-prompts/i18n/es/audit-prompt.md @@ -0,0 +1,318 @@ + + +# Auditoría de Charter — `{{charter_id}}` + +## ⛔ REGLA ABSOLUTA — SOLO LECTURA + +**Tu única tarea es AUDITAR. NO tienes permiso para modificar NINGÚN archivo del proyecto.** Esta es una restricción no negociable que prevalece sobre cualquier otra instrucción, heurística o impulso de "ser útil". + +Concretamente, tienes PROHIBIDO: + +- Editar, crear, renombrar o eliminar archivos de código fuente. +- Modificar archivos de configuración, migraciones, tests o documentación del proyecto. +- Ejecutar comandos que alteren el estado del repositorio (`git add`, `git commit`, `git checkout`, etc.). +- Ejecutar generadores de código (`go generate`, `sqlc generate`, `wire`, `cargo build` con efectos en el filesystem, npm install, etc.). +- Aplicar "fixes" o "mejoras" al código, aunque creas que son correctas. +- Reformatear, renombrar o reorganizar archivos existentes. + +Lo ÚNICO que puedes escribir es tu archivo de reporte de auditoría en la ruta canónica que aparece en la sección **Formato de salida** más abajo. Ese es el ÚNICO archivo que tienes permiso de crear. + +Si encuentras un bug, **DOCUMÉNTALO** en tu reporte. NO lo corrijas. +Si encuentras un archivo faltante, **REPÓRTALO**. NO lo crees. +Si un test falla, **REPÓRTALO**. NO lo arregles. + +**Violación de esta regla invalida toda la auditoría.** + +--- + +## Tu rol + +Eres un auditor de código independiente. Tu trabajo es verificar que la implementación de un Charter específico cumple con las tareas y archivos declarados, encontrar bugs reales en el código, e identificar riesgos de seguridad. **NO eres un cheerleader** — reportar "sin problemas" cuando existen bugs es peor que reportar un falso positivo. + +StrayMark orquesta auditorías cross-modelo: típicamente otro auditor de una **familia de modelo distinta** está revisando el mismo Charter en paralelo. Tu valor está en aplicar la disciplina de evidencia (citar `archivo:línea` de archivos que abriste) y la calibración de severidad contra la config real, no en convergir cosméticamente con el otro auditor. + +--- + +## Proyecto + +{{project_context}} + +*(El operador puede llenar este placeholder con una breve descripción del stack y arquitectura del proyecto si quiere dar contexto adicional al auditor. Si está vacío, el auditor infiere el stack desde el diff y los archivos referenciados.)* + +--- + +## Alcance ESTRICTO + +**Charter a auditar:** `{{charter_id}}` — {{charter_title}} +**Archivo del Charter:** `{{charter_path}}` +**Git range:** `{{git_range}}` + +La fuente autoritativa de alcance es el archivo del Charter en `{{charter_path}}`. Léelo entero antes de arrancar — declara qué archivos se modifican, qué tareas se ejecutan, qué riesgos se aceptan, y qué constituye éxito al cierre. + +### Reglas de alcance + +- Solo reporta hallazgos que afecten **archivos o tareas declarados en el Charter** o que aparezcan modificados en el `git_range`. +- Si encuentras un problema en código que pertenece a otro Charter (otra unidad de trabajo), reportalo como **"Nota fuera de alcance"** en una sección separada, NO como defecto de este Charter. +- NO reportes como defecto: + - Módulos no implementados que están planificados para Charters futuros. + - Wiring/DI no conectado si la tarea de wiring es de otro Charter. + - Integration tests faltantes si la tarea de tests es de otro Charter. + - Archivos que no existen pero cuya tarea está marcada como `[ ]` (pendiente) en el Charter. + +### Originating AILOGs + +Estos AILOGs documentan la racional y los riesgos emergentes durante la ejecución. **Léelos antes de auditar** — los R que ya están documentados ahí NO son hallazgos nuevos, son trade-offs aceptados conscientemente. + +``` +{{ailog_paths}} +``` + +```markdown +{{ailog_contents}} +``` + +--- + +## Charter content + +```markdown +{{charter_content}} +``` + +--- + +## Diff + +```diff +{{git_diff}} +``` + +--- + +## Qué debes hacer + +### Paso 1 — Leer el alcance + +Lee el archivo del Charter en `{{charter_path}}` completo. Identifica: + +- La sección `## Tasks` (o equivalente): cada tarea, su descripción y el archivo esperado. +- La sección `## Files to modify`: tabla de archivos y tipo de cambio declarado. +- La sección `## Risk` o equivalente: riesgos `R` aceptados conscientemente. +- El criterio de cierre del Charter (qué hace que esté "completo"). + +### Paso 2 — Verificar cada tarea (OBLIGATORIO) + +Para CADA tarea en el Charter, realiza estos pasos en orden: + +1. **Localizar archivo(s)**: encuentra el archivo mencionado en la tarea. Si no existe, reporta como "No encontrado". Si existe, continúa. +2. **Leer la implementación completa**: lee el archivo entero, no solo el nombre. **No reportes "archivo existe" sin leer su contenido.** +3. **Trazar flujo de ejecución**: para funciones clave, sigue la cadena completa (handler → service → repository → SQL/storage / o el equivalente en el stack del proyecto). Verifica que los parámetros se propaguen correctamente en cada capa. +4. **Verificar tests**: localiza los tests correspondientes. Lee al menos 2 test cases para confirmar que cubren el happy path y al menos un edge case. +5. **Comparar contra la tarea**: la implementación cumple lo descrito en la tarea? Si hay discrepancias, reporta con evidencia (`archivo:línea`). + +> **Disciplina de evidencia.** Solo puedes opinar sobre archivos que has abierto vía tool call (Read, Grep, etc.). Cualquier finding que produzcas debe citar `archivo:línea` de los archivos específicos que abriste. Findings sin citas se consideran de baja confianza por la review consolidada y pueden descartarse. Si no abriste un archivo, no puedes inferir comportamiento, estructura, ni corrección sobre él. + +### Paso 3 — Ejecutar verificaciones (cuando aplique) + +Si tu entorno te permite ejecutar comandos del proyecto (build, lint, test), ejecútalos sobre el alcance del Charter y reporta los resultados textualmente. **Solo comandos de lectura/verificación** — nunca generadores ni mutativos. + +> *Ejemplos por stack* (adapta al proyecto que estás auditando): +> - **Go**: `go vet ./...`, `go build ./...`, `go test .//... -v -count=1 2>&1 | tail -50` +> - **Rust**: `cargo check`, `cargo clippy --all-targets`, `cargo test --no-run` +> - **TypeScript/Node**: `npm run typecheck`, `npm run lint`, `npm test -- --run` +> - **Python**: `mypy `, `ruff check`, `pytest --co` + +Si tu entorno NO te permite ejecución de comandos, omite este paso y enfoca el audit en lectura estática de código + tests. + +### Paso 4 — Evaluar el cierre del Charter + +Lee el criterio de cierre declarado por el Charter. Evalúa: **se cumple este criterio con la implementación actual?** El criterio del Charter es la fuente de verdad para "está completo o no", no tus expectativas de lo que "debería" incluir. + +### Paso 5 — Calibrar severidad contra la configuración REAL del proyecto + +Antes de asignar severidad a CADA hallazgo, verifica el driver, flag o configuración realmente activa en el código, NO el caso teórico peor. + +**Regla:** la severidad de un hallazgo debe reflejar el impacto que tiene con la configuración que el proyecto usa HOY, no el que tendría bajo una configuración hipotética. + +**Verificaciones obligatorias antes de declarar severidad Crítica o Alta:** + +- [ ] **Driver activo**: si el hallazgo concierne a event bus, cache, storage, queue o cualquier componente pluggable, abre el factory/config (típicamente algo como `internal/core//factory.go`, `src//factory.ts`, `.env.example`, `config.yml`) y confirma cuál es el driver realmente instanciado. +- [ ] **Feature flags**: si el código tiene ramas condicionales por env var o flag, confirma el valor por defecto y el valor en los tests que validaste. Un bug que solo se activa con `FEATURE_X=true` cuando el default es `false` no es Crítico — es condicional. +- [ ] **Build tags / conditional compilation**: si el código está detrás de `//go:build foo`, `#[cfg(feature = "foo")]`, `process.env.NODE_ENV !== 'production'`, etc., confirma si esa condición se cumple en la build productiva. Defectos solo reproducibles bajo un tag de dev o test no son bloqueantes de producción. +- [ ] **Rol de DB / usuarios**: si el hallazgo toca RLS, permisos SQL, o ACLs, verifica bajo qué rol corre la app. (Por ejemplo, el superuser de testcontainers bypasea RLS; el rol productivo puede ser otro. No confundas comportamiento en tests con comportamiento productivo.) +- [ ] **Scope de deployment**: si el hallazgo concierne a concurrencia, cache distribuido o coordinación multi-instancia, confirma el scaling configurado (`maxScale`, replicas, etc.). Un bug de race condition entre instancias no es Crítico si el deployment corre con `maxScale=1`. + +**Cómo clasificar cuando el hallazgo es CONDICIONAL:** + +- **Crítico / Alto**: el bug se activa con la configuración que corre HOY en main o staging. +- **Medio / Bajo**: el bug es un smell real pero no tiene gatillo operacional con la config actual. +- **Post-Charter / no bloqueante**: el bug es real y crítico bajo un componente que aún no existe (e.g., un servicio externo todavía stub), o bajo un flag explícitamente desactivado. Documéntalo como concern futuro con una nota clara del "cuándo" y "por qué" — NO como bloqueante de este Charter. + +**Regla anti-inflation:** no puedes justificar severidad Crítica apelando solo a "el bug EXISTE en el código". Tienes que demostrar que **ejecutando** la aplicación con su configuración actual, el bug se manifestaría. Si tu justificación empieza con "si en el futuro se implementara X..." o "si alguien activara la flag Y...", tu severidad debe ser post-Charter o Medio con nota, no Crítico. + +**Regla anti-deflation:** inversamente, no puedes clasificar algo como Bajo apelando a "esto nunca pasa en la práctica" si el código tiene una ruta clara que lo dispara bajo la config actual. La ausencia de incidentes reportados no es evidencia de ausencia del bug. + +> **Ejemplo — diferimiento declarado, no defecto.** Supón que el Charter N introduce un adaptador in-memory delgado para un servicio que el proyecto planea respaldar con un driver real en un Charter futuro (digamos Charter N+K). La sección `## Risk` del Charter N nombra el diferimiento explícitamente (por ejemplo: *"R1: adaptador in-memory temporal, reemplazado en CHARTER-N+K"*). Si un auditor leyendo el Charter N abre el factory del componente y encuentra que el driver activo es el adaptador in-memory en lugar de la implementación real, **NO** debe reportar esto como hallazgo Crítico — el diferimiento es scope declarado, no deuda técnica oculta. La calibración correcta requiere abrir el factory y verificar el driver activo *antes* de declarar severidad alta; si el resultado coincide con un diferimiento declarado en algún Charter (este o uno previo), el hallazgo es a lo sumo *Post-Charter / no bloqueante*. Inversamente, si el mismo auditor encuentra otro lugar donde el mismo patrón se repitió **sin** un diferimiento declarado en ningún Charter, eso **sí** es hallazgo (deuda sin dueño). + +--- + +## Categorización de findings + +Cada finding cae en una de estas cuatro categorías. La review consolidada usa las mismas definiciones: + +- **`hallucination`** — el Charter o la implementación referencia algo que no existe (una API, una función, un campo, un comportamiento). El agente lo inventó. Verifica abriendo el archivo o la API real. +- **`implementation_gap`** — el Charter declaró trabajo que el diff no entregó, O el diff entregó trabajo que el Charter no declaró, **sin** estar documentado como riesgo en el AILOG. (Si está documentado en `## Risk` como `R` en algún AILOG, eso NO es gap — es trade-off aceptado.) +- **`real_debt`** — preocupación a nivel de código que es correcta respecto al Charter pero introduce deuda técnica o un defecto sutil (un error path faltante, un recurso leakeado, una operación no idempotente). El adoptante debería capturarlo como TDE doc post-audit. +- **`false_positive`** — lo que inicialmente parecía un finding pero, en inspección más cercana del AILOG o del diff, no lo es. Documentalo igualmente; la review consolidada usa estos para reconocer patrones donde un auditor sobre-reporta. + +--- + +## Formato de salida + +Documenta tus hallazgos en un archivo markdown. La ruta canónica de salida la decide el flujo: + +- En modo CLI auditor-side (skill `straymark-audit-execute`): `.straymark/audits/{{charter_id}}/report-.md` (la skill maneja el path automáticamente). +- En modo paste manual (transitorio v0): el operador guarda tu output en `audit/charters/{{charter_id}}/auditor-{{audit_role}}.md` o convención equivalente. + +El archivo debe tener este frontmatter (validado contra `{{schema_path}}`): + +```yaml +--- +audit_role: auditor # v1 unificado. Legacy v0: "auditor-primary" o "auditor-secondary" +auditor: # ej. claude-sonnet-4-6, gemini-2.5-pro, copilot-v1.0.40 +charter_id: {{charter_id}} +git_range: "{{git_range}}" +prompt_used: +audited_at: +findings_total: +findings_by_category: + hallucination: + implementation_gap: + real_debt: + false_positive: +evidence_citations: # opcional pero recomendado: cuántos archivo:línea citaste +audit_quality: high|medium|low # opcional, autoevaluación +--- + +# Auditoría: {{charter_id}} por + +## Resumen ejecutivo + +[1-2 párrafos: ¿la ejecución coincidió con el alcance declarado del Charter? ¿Cuál es el veredicto general — limpio, parcial, desviado? ¿Cuál es el hallazgo más material si lo hay?] + +## Verificación de compilación y tests + +[Pega aquí la salida de los comandos del Paso 3, si los corriste. Si no, indica "(omitido — sin acceso a ejecución de comandos)".] + +## Trazabilidad tarea por tarea + +Para CADA tarea del Charter, una entrada con este formato: + +### T### — [Descripción de la tarea] + +- **Archivo(s)**: `path/to/file.ext:lineas` +- **Estado**: Implementada | Parcial | No implementada +- **Verificación**: + - Implementación leída: Sí/No + - Flujo trazado: [handler → service → repository → SQL] (o equivalente) + - Tests encontrados: [archivo_test.ext, N test cases] +- **Hallazgos**: [Ninguno | Descripción del hallazgo con `archivo:línea`] + +## Hallazgos + +Clasificados por severidad. SOLO hallazgos dentro del alcance del Charter. + +### Críticos (bloquean el cierre del Charter) + +| # | Hallazgo | Archivo:Línea | Categoría | Evidencia | Remediación sugerida | +|---|----------|---------------|-----------|-----------|---------------------| + +### Altos (bugs de seguridad o lógica) + +| # | Hallazgo | Archivo:Línea | Categoría | Evidencia | Remediación sugerida | +|---|----------|---------------|-----------|-----------|---------------------| + +### Medios (inconsistencias, riesgos menores) + +| # | Hallazgo | Archivo:Línea | Categoría | Evidencia | Remediación sugerida | +|---|----------|---------------|-----------|-----------|---------------------| + +### Bajos (mejoras de calidad, naming, estilo) + +| # | Hallazgo | Archivo:Línea | Categoría | Evidencia | Remediación sugerida | +|---|----------|---------------|-----------|-----------|---------------------| + +## Notas fuera de alcance (opcional) + +Observaciones sobre código que NO es parte del alcance de este Charter pero que consideras relevante mencionar. Estas NO son defectos de este Charter. + +| Observación | Charter / area pertinente | Nota | +|-------------|---------------------------|------| + +## Evaluación del cierre del Charter + +¿Se cumple el criterio de cierre declarado por `{{charter_id}}`? +[Sí / No / Parcial] — [Justificación basada en evidencia, citando `archivo:línea`] + +## Conclusión + +[2-3 oraciones. Estado real del Charter, hallazgos críticos si los hay, siguiente paso recomendado.] +``` + +--- + +## Lo que NO debes hacer + +- **NO MODIFIQUES NINGÚN ARCHIVO DEL PROYECTO.** Tu único output permitido es el reporte de auditoría. Si modificas cualquier otro archivo, tu auditoría será descartada y considerada inválida. Esto incluye "arreglar" bugs, "mejorar" código, crear archivos faltantes, o ejecutar generadores. **REPORTA, NO ACTÚES.** Esta no es opcional ni contextual — es una restricción absoluta. +- **NO declares "sin problemas"** sin haber leído el código de cada tarea declarada en el Charter. +- **NO reportes tareas de otros Charters** como defectos de éste. +- **NO infles severidad**: un hallazgo de otro Charter no es "Crítico" en éste. +- **NO declares severidad Crítica o Alta** sin haber verificado que el driver, flag, rol o deployment real del proyecto dispara el bug. Ver Paso 5. Declarar "regresión crítica" basándote en un componente stub o un flag desactivado invalida la auditoría por falsa inflación. +- **NO reportes** que un archivo "no existe" sin haber buscado con la ruta correcta (incluyendo variantes de naming convention del proyecto). +- **NO copies la estructura de archivos** sin verificar contenido. +- **NO ignores** las carpetas de auditorías previas (típicamente `audit/` o `.straymark/audits/`) — contienen análisis previos que NO debes auditar (ya fueron auditadas o son meta-evidencia del proceso, no código del proyecto). +- **NO ejecutes** comandos destructivos o generativos. Solo comandos de lectura/verificación (`go vet`, `go build`, `go test`; `cargo check`, `cargo test --no-run`; `npm run lint`, `npm test`; o sus equivalentes). +- **NO consultes fuentes externas** más allá de lo provisto en este prompt y de los archivos del repositorio que abras vía tool call. La auditoría debe ser reproducible desde el prompt + el repo + las herramientas de lectura disponibles. + +--- + +*Plantilla unificada StrayMark v1 — traducción ES. Las siete secciones universales (REGLA ABSOLUTA, Tu rol, Reglas de alcance, Paso 2 verificación obligatoria, Paso 5 calibración de severidad, Lo que NO debes hacer, Formato de salida) provienen del skill `audit/SKILL.md` maduro pre-StrayMark de Sentinel, contribuido vía issue #102 por José Villaseñor Montfort (StrangeDaysTech). Hardcodes específicos a Sentinel (paths de specs, headings de Etapa, módulos internos) parametrizados contra el Charter doc, originating AILOGs, git range y project context.* diff --git a/.straymark/config.yml b/.straymark/config.yml new file mode 100644 index 0000000..ca453d3 --- /dev/null +++ b/.straymark/config.yml @@ -0,0 +1,28 @@ +# StrayMark Configuration +# https://github.com/StrangeDaysTech/straymark + +# Language setting for templates and documentation +# Supported values: en, es, zh-CN +# Default: en (English) +language: en + +# Regional regulatory scope. +# Controls which compliance frameworks are evaluated by `straymark compliance` +# and which document types are exposed by `straymark new`. +# +# global → NIST AI RMF + ISO/IEC 42001 (always recommended) +# eu → EU AI Act + GDPR +# china → TC260 v2.0, PIPL/PIPIA, GB 45438, CAC, +# GB/T 45652, CSL 2026 incident reporting +# +# Default if omitted: [global, eu] +# Add "china" only if your project operates in mainland China. +# regional_scope: +# - global +# - eu +# # - china + +# Complexity analysis settings (used by: straymark analyze) +# Uncomment to override the default cognitive complexity threshold +# complexity: +# threshold: 8 diff --git a/.devtrail/dist-manifest.yml b/.straymark/dist-manifest.yml similarity index 59% rename from .devtrail/dist-manifest.yml rename to .straymark/dist-manifest.yml index 07819cf..2666972 100644 --- a/.devtrail/dist-manifest.yml +++ b/.straymark/dist-manifest.yml @@ -1,13 +1,16 @@ -version: 4.1.0 -description: DevTrail distribution manifest +version: 4.17.0 +description: StrayMark distribution manifest files: -- .devtrail/ -- DEVTRAIL.md +- .straymark/ +- STRAYMARK.md - .claude/skills/ - .gemini/skills/ - .agent/workflows/ - .github/workflows/docs-validation.yml injections: +- target: AGENTS.md + template: dist-templates/directives/AGENTS.md + embed: null - target: CLAUDE.md template: dist-templates/directives/CLAUDE.md embed: null @@ -19,7 +22,7 @@ injections: embed: null - target: .cursorrules template: dist-templates/directives/cursorrules - embed: DEVTRAIL.md -- target: .cursor/rules/devtrail.md - template: dist-templates/directives/cursor-rules-devtrail.md - embed: DEVTRAIL.md + embed: STRAYMARK.md +- target: .cursor/rules/straymark.md + template: dist-templates/directives/cursor-rules-straymark.md + embed: STRAYMARK.md diff --git a/.straymark/hooks/pre-pr.sh b/.straymark/hooks/pre-pr.sh new file mode 100644 index 0000000..039b85b --- /dev/null +++ b/.straymark/hooks/pre-pr.sh @@ -0,0 +1,71 @@ +#!/usr/bin/env bash +# pre-pr.sh — Run `straymark charter drift` on any Charter currently +# `status: in-progress` before opening a PR. Designed to be installed via +# `straymark init --hooks` as a git pre-push hook, or invoked manually +# (e.g., from a Makefile target) when the operator prefers explicit invocation. +# +# Behavior: +# - For each Charter in .straymark/charters/*.md whose frontmatter has +# `status: in-progress`, run `straymark charter drift --range +# ..HEAD`. AILOG-suppression in the CLI silences alerts on +# paths already documented as risks in the Charter's originating AILOGs. +# - Exits 0 when there's nothing in-progress, or when all in-progress +# Charters report clean (or AILOG-suppressed) drift. +# - Exits 1 when at least one Charter reports unaccounted drift, with a +# human-readable summary pointing to remediation paths. +# +# Configuration (environment): +# STRAYMARK_UPSTREAM git ref to compare HEAD against (default: origin/main) +# +# Why this is opt-in: per straymark-design-principles.md §6, friction is +# virtuous when the operator consents to it. We never install this hook +# automatically; adopters opt in via `straymark init --hooks` or by copying +# this file into .git/hooks/pre-push themselves. + +set -euo pipefail + +if ! command -v straymark >/dev/null 2>&1; then + # straymark not installed (or not in PATH); the hook should be transparent + # rather than blocking pushes for adopters who haven't yet opted in. + exit 0 +fi + +UPSTREAM="${STRAYMARK_UPSTREAM:-origin/main}" + +if [ ! -d .straymark/charters ]; then + exit 0 # repo doesn't use Charters +fi + +charters=$(grep -l '^status: in-progress' .straymark/charters/*.md 2>/dev/null || true) +if [ -z "$charters" ]; then + exit 0 # nothing in-progress; nothing to check +fi + +echo "[straymark pre-pr] Checking drift on in-progress Charters (range: $UPSTREAM..HEAD)..." +echo "" + +exit_code=0 +for charter_file in $charters; do + charter_id=$(awk '/^charter_id:/ {print $2; exit}' "$charter_file" | tr -d '"') + if [ -z "$charter_id" ]; then + echo " [skip] $charter_file has no charter_id in frontmatter" + continue + fi + echo " -- $charter_id ($charter_file) --" + if ! straymark charter drift "$charter_id" --range "$UPSTREAM..HEAD"; then + exit_code=1 + fi + echo "" +done + +if [ $exit_code -ne 0 ]; then + echo "" + echo "[straymark pre-pr] Drift detected on at least one Charter." + echo " - Address it before opening the PR (see hints above), or" + echo " - Document the drift in an AILOG under '## Risk' as 'R" + echo " (new, not in Charter)' so the next run suppresses it, or" + echo " - Bypass with 'git push --no-verify' if the drift is intentional" + echo " and acknowledged." +fi + +exit $exit_code diff --git a/.straymark/schemas/audit-output.schema.v0.json b/.straymark/schemas/audit-output.schema.v0.json new file mode 100644 index 0000000..993e63a --- /dev/null +++ b/.straymark/schemas/audit-output.schema.v0.json @@ -0,0 +1,168 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://straymark.dev/schemas/audit-output.schema.v0.json", + "title": "StrayMark Charter Audit Output (experimental v0)", + "description": "Frontmatter schema for the markdown files that auditors and the calibrator-reconciler produce during a `straymark charter audit` cycle. The shape distinguishes auditor outputs (with fresh findings) from calibrator outputs (reconciliation across N auditor outputs) via the `audit_role` field. v1 unifies auditors under a single role (`auditor`) and supports N≥2 auditors per cycle; legacy values `auditor-primary` and `auditor-secondary` from v0 are still accepted during the transition.", + "$comment": "EXPERIMENTAL v0.x. Phase 3 of the CLI roadmap. Crystallized from the dual-audit pattern validated empirically in Sentinel (Copilot + Gemini + claude-analisis across 6 cycles). v0.x evolves to support v1 audit-skills (see Propuesta/straymark-audit-cli-flow.md): unified `audit_role: auditor` for any number of auditors per cycle, optional `evidence_citations` count for review weighting. Will not stabilize to v1.0 until validated in a second domain. The schema is for the YAML inside the file's frontmatter; the body is free-form markdown by convention. The findings_by_category enum (hallucination | implementation_gap | real_debt | false_positive) is the same one used by `external_audit` in charter-telemetry.schema.v0.json — the audit cycle output integrates directly into the Charter telemetry at close time.", + "type": "object", + "oneOf": [ + { "$ref": "#/$defs/auditorOutput" }, + { "$ref": "#/$defs/calibratorOutput" } + ], + "$defs": { + "auditorOutput": { + "type": "object", + "required": [ + "audit_role", + "auditor", + "charter_id", + "git_range", + "prompt_used", + "audited_at", + "findings_total", + "findings_by_category" + ], + "additionalProperties": true, + "properties": { + "audit_role": { + "type": "string", + "enum": ["auditor", "auditor-primary", "auditor-secondary"], + "description": "Role this output occupies. v1 (preferred): the unified value `auditor` — any number of auditors per cycle, distinguished by their `auditor` model identifier and the canonical filename `report-.md`. v0 legacy (still accepted during the v0→v1 transition): `auditor-primary` or `auditor-secondary` from the dual-audit pattern. New audits should use `auditor`." + }, + "auditor": { + "type": "string", + "minLength": 1, + "description": "Model identifier and version of the auditor that produced this output (e.g., `copilot-v1.0.37`, `gemini-cli-v1.5`, `claude-opus-4`). Free-form so adopters can use any model identifier." + }, + "charter_id": { + "type": "string", + "pattern": "^CHARTER-[0-9]{2,}(-[a-z0-9-]+)?$" + }, + "git_range": { + "type": "string", + "minLength": 1, + "description": "Git revision range the auditor reviewed (e.g., `origin/main..HEAD`)." + }, + "prompt_used": { + "type": "string", + "minLength": 1, + "description": "Path (relative to the audit directory) of the resolved prompt file the auditor was given. Required so the operator can verify the prompt wasn't tampered with mid-cycle. Closes RFC #82." + }, + "audited_at": { + "type": "string", + "format": "date" + }, + "findings_total": { + "type": "integer", + "minimum": 0 + }, + "findings_by_category": { + "type": "object", + "additionalProperties": false, + "properties": { + "hallucination": { "type": "integer", "minimum": 0 }, + "implementation_gap": { "type": "integer", "minimum": 0 }, + "real_debt": { "type": "integer", "minimum": 0 }, + "false_positive": { "type": "integer", "minimum": 0 } + } + }, + "audit_quality": { + "type": "string", + "enum": ["high", "medium", "low"], + "description": "Operator's calibration of this auditor's output quality. Optional — set when consolidating into telemetry." + }, + "evidence_citations": { + "type": "integer", + "minimum": 0, + "description": "How many `path:line` citations the auditor included in the body. Optional, recommended. The review skill uses this for finding-weighting: high-citation reports indicate the auditor exercised the tool-use discipline (Paso 2 of the prompt), low-citation reports may have extended training assumptions and are weighted accordingly. Empty audits with `findings_total: 0` legitimately have `evidence_citations: 0`." + } + } + }, + "calibratorOutput": { + "type": "object", + "required": [ + "audit_role", + "calibrator", + "charter_id", + "git_range", + "prompt_used", + "calibrated_at", + "auditors_reconciled", + "findings_consolidated" + ], + "additionalProperties": true, + "properties": { + "audit_role": { + "type": "string", + "const": "calibrator-reconciler" + }, + "calibrator": { + "type": "string", + "minLength": 1, + "description": "Model identifier of the calibrator. May be of any family — even the same as the implementer — because the calibrator's job is to apply the schema definitionally over already-produced auditor verdicts, not to discover gaps. Heterogeneity matters for the auditor pair, not the calibrator (see roadmap §5.2)." + }, + "charter_id": { + "type": "string", + "pattern": "^CHARTER-[0-9]{2,}(-[a-z0-9-]+)?$" + }, + "git_range": { + "type": "string", + "minLength": 1 + }, + "prompt_used": { + "type": "string", + "minLength": 1 + }, + "calibrated_at": { + "type": "string", + "format": "date" + }, + "auditors_reconciled": { + "type": "array", + "minItems": 2, + "items": { + "type": "string", + "minLength": 1, + "description": "Path (relative to audit dir) of an auditor output file this calibration considered." + }, + "description": "Auditor outputs reconciled in this calibration. Minimum 2 (heterogeneity inter-family is the discovery mechanism). v1 supports N≥2; high-risk Charters or specialized scopes may reconcile 3 or 4 auditors when the operator opts in." + }, + "findings_consolidated": { + "type": "integer", + "minimum": 0, + "description": "Total distinct findings after reconciliation (after deduplication and rejection of false positives identified across both auditors)." + }, + "findings_by_status": { + "type": "object", + "additionalProperties": false, + "properties": { + "agreed": { + "type": "integer", + "minimum": 0, + "description": "Both auditors flagged the same finding (highest signal — convergence)." + }, + "disputed": { + "type": "integer", + "minimum": 0, + "description": "Auditors flagged but disagreed on category; calibrator picked one." + }, + "unique_primary": { + "type": "integer", + "minimum": 0, + "description": "Only the primary auditor flagged this; calibrator validated as legitimate." + }, + "unique_secondary": { + "type": "integer", + "minimum": 0 + }, + "rejected": { + "type": "integer", + "minimum": 0, + "description": "Both auditors flagged but calibrator determined false positive." + } + } + } + } + } + } +} diff --git a/.straymark/schemas/charter-telemetry.schema.v0.json b/.straymark/schemas/charter-telemetry.schema.v0.json new file mode 100644 index 0000000..c86b732 --- /dev/null +++ b/.straymark/schemas/charter-telemetry.schema.v0.json @@ -0,0 +1,281 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://straymark.dev/schemas/charter-telemetry.schema.v0.json", + "title": "StrayMark Charter Telemetry (experimental v0)", + "description": "Schema for the post-execution telemetry recorded at Charter close. See Propuesta/straymark-charter-telemetry.md v0.3 for the questions this instrumentation is designed to answer and the empirical evidence behind each field.", + "$comment": "EXPERIMENTAL v0. Derived from 5 PLAN-NN.telemetry.yaml files in Sentinel (one project, Go backend) — same N=1-domain caveat as charter.schema.v0.json. Will not stabilize to v1.0 until validated in a second domain. The 4 fields refined by Sentinel relative to v0.1 of the doc are: external_audit as array (dual-audit calibration), outcome.scope_change_notes with F1...FN encoding, agent_quality.r_n_plus_one_emergent_count, qualitative.format_iteration. v0.2 addendum (fw-4.16.0, 2026-05-15): added optional `pre_declare_refresh` and `post_close_amendment` sub-objects per Issue #156 (Sentinel CHARTER-18 RFC). Both validated in Sentinel only; the N=1-domain caveat still applies — fields are opt-in and absent by default. Adopters: this schema is for the YAML inside the top-level `charter_telemetry:` key in .straymark/charters/CHARTER-NN.telemetry.yaml — not for the file itself.", + "type": "object", + "required": ["charter_telemetry"], + "additionalProperties": false, + "properties": { + "charter_telemetry": { + "type": "object", + "required": ["charter_id", "charter_title", "closed_at", "effort", "outcome"], + "additionalProperties": false, + "properties": { + "charter_id": { + "type": "string", + "pattern": "^CHARTER-[0-9]{2,}(-[a-z0-9-]+)?$", + "description": "Charter identifier this telemetry corresponds to. Must match the charter_id of an existing Charter file in .straymark/charters/." + }, + "charter_title": { + "type": "string", + "minLength": 1, + "description": "Short title of the Charter, copied for human-readability in the telemetry file." + }, + "closed_at": { + "type": "string", + "format": "date", + "description": "Date when the Charter was closed (YYYY-MM-DD). Conventionally the same date as the closing commit." + }, + + "originating_ailogs": { + "type": "array", + "description": "AILOGs that motivated the Charter, with retrospective notes on whether they remained relevant at execution time.", + "items": { + "type": "object", + "required": ["ailog_id", "still_relevant_at_execution"], + "additionalProperties": false, + "properties": { + "ailog_id": { + "type": "string", + "pattern": "^AILOG-[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{3}[a-z]?(-[a-z0-9-]+)?$" + }, + "still_relevant_at_execution": { "type": "boolean" }, + "relevance_notes": { "type": "string" } + } + } + }, + + "trigger": { + "type": "object", + "description": "Whether the declared trigger fired cleanly. Sentinel observed that declared triggers were prescriptive, not predictive (5/5 Plans fired on meta-experiment signal). Capturing the gap is the point.", + "additionalProperties": false, + "properties": { + "declared_kind": { + "type": "string", + "enum": ["event_trigger", "date", "metric_threshold", "infrastructure_milestone"] + }, + "declared_description": { "type": "string" }, + "fired_at": { "type": "string", "format": "date" }, + "fire_clarity": { + "type": "string", + "enum": ["clear", "ambiguous", "manually_decided"] + }, + "fire_clarity_notes": { "type": "string" } + } + }, + + "pre_work": { + "type": "object", + "description": "Whether the §Pre-trabajo section in the Charter was honored. items_discovered_during_planning being high signals the field is not doing its job.", + "additionalProperties": false, + "properties": { + "items_declared": { "type": "integer", "minimum": 0 }, + "items_completed_before_planning": { "type": "integer", "minimum": 0 }, + "items_skipped": { "type": "integer", "minimum": 0 }, + "items_discovered_during_planning": { "type": "integer", "minimum": 0 }, + "pre_work_quality": { "type": "string", "enum": ["high", "medium", "low"] }, + "pre_work_notes": { "type": "string" } + } + }, + + "planning_session": { + "type": "object", + "description": "Optional — many Charters execute without a formal planning session. Set occurred:false to skip the rest.", + "additionalProperties": false, + "required": ["occurred"], + "properties": { + "occurred": { "type": "boolean" }, + "duration_minutes": { "type": "integer", "minimum": 0 }, + "participants": { "type": "integer", "minimum": 0 }, + "decisions_made": { "type": "integer", "minimum": 0 }, + "decisions_deferred": { "type": "integer", "minimum": 0 }, + "notes": { "type": "string" } + } + }, + + "effort": { + "type": "object", + "description": "Estimation accuracy — TIME only. Line-count was retired in Sentinel (drift 1.0x to 8.1x; not predictive).", + "required": ["estimated_effort", "actual_effort"], + "additionalProperties": false, + "properties": { + "started_at": { "type": "string", "format": "date" }, + "finished_at": { "type": "string", "format": "date" }, + "estimated_effort": { + "type": "string", + "pattern": "^(XS|S|M|L)( \\(~.+\\))?$", + "description": "XS/S/M/L bucket plus optional ~time hint, e.g., 'M (~1.5h)'." + }, + "actual_effort": { + "type": "string", + "pattern": "^(XS|S|M|L)( \\(~.+\\))?$" + }, + "estimation_drift_factor": { + "type": "number", + "minimum": 0, + "description": "actual / estimated TIME ratio. 1.0 = perfect estimate." + }, + "estimation_drift_reason": { "type": "string" } + } + }, + + "agent_quality": { + "type": "object", + "description": "Signal about the agent's behavior during execution, not just deliverables.", + "additionalProperties": false, + "properties": { + "sessions_count": { "type": "integer", "minimum": 0 }, + "hallucinations_caught": { "type": "integer", "minimum": 0 }, + "hallucination_categories": { + "type": "array", + "items": { "type": "string" } + }, + "decisions_contradicting_prior_adrs": { "type": "integer", "minimum": 0 }, + "contradiction_notes": { "type": "string" }, + "context_loaded_was_sufficient": { "type": "boolean" }, + "additional_context_loaded_manually": { + "type": "integer", + "minimum": 0, + "description": "Files the operator had to load manually mid-execution because the initial context was insufficient. PLAN-06 = 6." + }, + "r_n_plus_one_emergent_count": { + "type": "integer", + "minimum": 0, + "description": "Risks named explicitly during execution that were not in the declared §Risks list. Validated in 4/4 Sentinel cycles as cross-agent signal." + }, + "skill_prompts_used": { + "type": "array", + "items": { "type": "string" } + } + } + }, + + "external_audit": { + "type": "array", + "description": "Array (not single object) — Sentinel validated dual-audit (Copilot + Gemini) as cross-model calibration. The categorization delta between auditors is itself signal.", + "items": { + "type": "object", + "required": ["auditor", "findings_total"], + "additionalProperties": false, + "properties": { + "auditor": { "type": "string", "minLength": 1 }, + "findings_total": { "type": "integer", "minimum": 0 }, + "findings_by_category": { + "type": "object", + "additionalProperties": false, + "properties": { + "hallucination": { "type": "integer", "minimum": 0 }, + "implementation_gap": { "type": "integer", "minimum": 0 }, + "real_debt": { "type": "integer", "minimum": 0 }, + "false_positive": { "type": "integer", "minimum": 0 } + } + }, + "audit_quality": { "type": "string", "enum": ["high", "medium", "low"] }, + "audit_notes": { "type": "string" } + } + } + }, + + "outcome": { + "type": "object", + "required": ["completed_as_planned", "scope_changes"], + "additionalProperties": false, + "properties": { + "completed_as_planned": { "type": "boolean" }, + "scope_changes": { "type": "string", "enum": ["ninguno", "menor", "mayor"] }, + "scope_change_notes": { + "type": "string", + "description": "Free text. Convention: F1...FN encoding consistent with claude-analisis output, with optional category tag — e.g. 'F1 (IG): drift declared-vs-implemented in handler.go'. IG=implementation gap, FP=false positive." + }, + "new_followups_generated": { "type": "integer", "minimum": 0 }, + "new_charters_created": { "type": "integer", "minimum": 0 }, + "charters_invalidated": { "type": "integer", "minimum": 0 }, + "associated_stage_id": { "type": "string" } + } + }, + + "pre_declare_refresh": { + "type": "object", + "description": "Optional. Populate if this Charter was preceded by a SpecKit refresh PR per the Charter-chain-evolution pattern (see .straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md Pattern 1). Absence means the pattern was not applied.", + "additionalProperties": false, + "required": ["enabled"], + "properties": { + "enabled": { + "type": "boolean", + "description": "True if a refresh PR landed before this Charter's declare." + }, + "refresh_pr": { + "type": ["string", "null"], + "description": "URL or short ref of the refresh PR (e.g. owner/repo#76). Null if enabled but not yet linked." + }, + "refresh_aidec": { + "type": ["string", "null"], + "description": "AIDEC id ratifying the refresh decision (e.g. AIDEC-YYYY-MM-DD-NNN-slug). Null if no AIDEC was filed." + }, + "reusable_patterns_integrated": { "type": "integer", "minimum": 0 }, + "code_gaps_integrated": { "type": "integer", "minimum": 0 }, + "discipline_patterns_integrated": { "type": "integer", "minimum": 0 }, + "empirical_corrections_integrated": { "type": "integer", "minimum": 0 }, + "operator_decisions_ratified": { "type": "integer", "minimum": 0 } + } + }, + + "post_close_amendment": { + "type": "object", + "description": "Optional. Populate if this Charter received a Batch N.4 amendment after `status: closed` (see .straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md Pattern 2). Absence means no post-close amendment occurred.", + "additionalProperties": false, + "required": ["applied"], + "properties": { + "applied": { + "type": "boolean", + "description": "True if a post-close amendment commit landed on the same execute branch." + }, + "trigger": { + "type": "string", + "enum": ["external_audit", "production_incident", "deferred_implementation"], + "description": "What surfaced the need for the amendment after close." + }, + "ailog_id": { + "type": "string", + "pattern": "^AILOG-[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{3}[a-z]?(-[a-z0-9-]+)?$", + "description": "The AILOG that documents the amendment (NEW, not amending the original — the original gets a `## Historical correction` subsection pointing forward to this id)." + }, + "findings_closed": { "type": "integer", "minimum": 0 }, + "files_modified": { "type": "integer", "minimum": 0 }, + "effort_hours": { "type": "number", "minimum": 0 } + } + }, + + "qualitative": { + "type": "object", + "description": "Where the insight usually lives. Quantitative fields show what happened; qualitative shows what to change.", + "additionalProperties": false, + "properties": { + "format_iteration": { + "type": "string", + "description": "Which format version of the Charter template was used (e.g., v3, v4). Self-evolving: each Charter refines the format of the next." + }, + "friction_points": { + "type": "array", + "items": { "type": "string" } + }, + "wins": { + "type": "array", + "items": { "type": "string" } + }, + "overall_satisfaction": { + "type": "integer", + "minimum": 1, + "maximum": 5, + "description": "1-5 score for how useful the Charter format was in this case." + }, + "would_repeat_format": { "type": "boolean" }, + "proposed_format_changes": { "type": "string" } + } + } + } + } + } +} diff --git a/.straymark/schemas/charter.schema.v0.json b/.straymark/schemas/charter.schema.v0.json new file mode 100644 index 0000000..06bf6ba --- /dev/null +++ b/.straymark/schemas/charter.schema.v0.json @@ -0,0 +1,49 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://straymark.dev/schemas/charter.schema.v0.json", + "title": "StrayMark Charter (experimental v0)", + "description": "Frontmatter schema for a StrayMark Charter — a bounded, auditable unit of work declared ex-ante and verified ex-post. See straymark-cli-roadmap.md §3.1 and que-es-un-charter.md for the conceptual scope.", + "$comment": "EXPERIMENTAL v0. Crystallized from Sentinel /plan-audit (6 cycles, format v1 → v2 → v3). Will not stabilize to v1.0 until validated in a second domain (frontend, ML pipeline, or infra-as-code). See straymark-thesis-validation.md §6 for the N≈2-3 argument. Adopters: avoid persisting tooling that depends on this exact shape; expect breaking changes between v0.x revisions.", + "type": "object", + "required": ["charter_id", "status", "effort_estimate", "trigger"], + "additionalProperties": true, + "properties": { + "charter_id": { + "type": "string", + "pattern": "^CHARTER-[0-9]{2,}(-[a-z0-9-]+)?$", + "description": "Unique Charter identifier. Format: CHARTER-NN where NN is project-local sequential, zero-padded to at least 2 digits. Optionally followed by a slug (e.g., CHARTER-05-per-service-thresholds)." + }, + "status": { + "type": "string", + "enum": ["declared", "in-progress", "closed"], + "description": "Lifecycle status of the Charter. Source of truth — the prose status mirror in the body is decorative." + }, + "effort_estimate": { + "type": "string", + "enum": ["XS", "S", "M", "L"], + "description": "Time-based effort estimate. Sentinel validated this as predictive (1.0x in 4/5 cycles); line-count is not predictive and is intentionally absent." + }, + "trigger": { + "type": "string", + "minLength": 1, + "description": "Free-text observable signal that justifies executing this Charter now (e.g., 'first false-positive ticket in svc_xxx', 'when admin UI lands'). Per Sentinel telemetry, declared triggers tend to be prescriptive, not predictive — track effective trigger separately at closure." + }, + "originating_ailogs": { + "type": "array", + "items": { + "type": "string", + "pattern": "^AILOG-[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{3}[a-z]?(-[a-z0-9-]+)?$" + }, + "minItems": 1, + "description": "AILOG IDs that motivated this Charter. Used in maintenance / post-MVP mode (the Sentinel case). Mutually exclusive with originating_spec; both may be absent if the Charter was scaffolded without an explicit origin." + }, + "originating_spec": { + "type": "string", + "minLength": 1, + "description": "Path (relative to project root) to a SpecKit spec.md or equivalent (e.g., 'specs/001-feature/spec.md'). Used in greenfield mode where SpecKit drives planning. Free-form to avoid coupling the schema to a specific SpecKit version. Mutually exclusive with originating_ailogs." + } + }, + "not": { + "required": ["originating_ailogs", "originating_spec"] + } +} diff --git a/.straymark/scripts/check-charter-drift.sh b/.straymark/scripts/check-charter-drift.sh new file mode 100644 index 0000000..877c8a4 --- /dev/null +++ b/.straymark/scripts/check-charter-drift.sh @@ -0,0 +1,213 @@ +#!/usr/bin/env bash +# check-charter-drift.sh — flag declared-but-not-modified files at Charter close. +# +# Ported from Sentinel scripts/check-plan-drift.sh (validated empirically with +# zero false positives across PLAN-05 retrospective + PLAN-06 prospective). +# StrayMark surface: Charters live at .straymark/charters/NN-slug.md (this is +# the rebrand of Sentinel's docs/plans/NN-*.md layout). +# +# This script catches drifts of OMISSION (file declared in Charter, never touched) +# and SCOPE EXPANSION (file modified but not declared). Both kinds were caught by +# external auditors in PLAN-05 (F4 evaluator_test gap, F5 architectural hallucination, +# modified extras like wire_gen.go). +# +# Usage: +# .straymark/scripts/check-charter-drift.sh +# +# Examples: +# .straymark/scripts/check-charter-drift.sh .straymark/charters/01-format-v4.md fd65e87..473f6e0 +# .straymark/scripts/check-charter-drift.sh .straymark/charters/01-format-v4.md HEAD~1..HEAD +# +# Exit codes: +# 0 — no drift detected (or only documented out-of-scope extras) +# 1 — drift found that needs attention (declared-but-not-modified or +# undocumented scope expansion) +# 2 — usage error +# +# Output is human-readable; the agent reading this should take action by either +# completing the missing work or documenting the drift in the AILOG under +# "## Risk" as `R (new, not in Charter)`. +# +# Note: `straymark charter drift` (cli-3.7.0+) wraps this script and adds +# AILOG-awareness — it suppresses alerts on paths already documented as R +# in any AILOG referenced by the Charter's `originating_ailogs` frontmatter. +# Invoking this script directly is fine but you'll see those documented-drift +# alerts as well; use the CLI for the de-noised view. + +set -euo pipefail + +if [ $# -lt 2 ]; then + echo "Usage: $0 " >&2 + echo "Example: $0 .straymark/charters/01-format-v4.md fd65e87..473f6e0" >&2 + exit 2 +fi + +CHARTER_FILE="$1" +GIT_RANGE="$2" + +if [ ! -f "$CHARTER_FILE" ]; then + echo "ERROR: Charter file not found: $CHARTER_FILE" >&2 + exit 2 +fi + +# Extract declared files from the "## Files to modify" / "## Archivos a modificar" +# / "## 要修改的文件" section. Reads the section delimited by the heading and the +# next `## ` heading. For markdown table rows (`| col1 | col2 | ...`) the script +# extracts only column 1 — the "File" column — to avoid false positives from +# backtick-quoted path references in the "Change" column (F3 of the +# CHARTER-02 telemetry, fw-4.6.0). Non-table content (bullets, prose) is +# preserved as-is for backward compatibility with adopters who use bullet lists +# instead of tables. +declared=$(awk ' + /^## (Files to modify|Archivos a modificar|要修改的文件)/ { in_table=1; next } + in_table && /^## / { in_table=0 } + in_table { + if (/^\|/) { + # Markdown table row. After splitting on |, cols[1] is empty (text + # before the leading |), cols[2] is the first column, etc. + n = split($0, cols, "|") + if (n >= 2) { + col1 = cols[2] + # Trim whitespace. + sub(/^[ \t]+/, "", col1) + sub(/[ \t]+$/, "", col1) + # Skip separator row (only dashes/spaces/colons) and header + # row variants. The grep below filters non-paths anyway, but + # silencing these here keeps awk output clean. + if (col1 ~ /^[-: ]+$/) next + if (col1 ~ /^[*]*[Ff]ile[*]*$/) next + if (col1 ~ /^[*]*[Aa]rchivo[*]*$/) next + if (col1 ~ /^[*]*文件[*]*$/) next + print col1 + } + } else { + # Non-table content (bullets, prose) — preserve current behavior. + print + } + } +' "$CHARTER_FILE" | grep -oP '`\K[^`]+(?=`)' | grep -E '\.(go|sql|yaml|yml|md|sh|ts|tsx|js|jsx|rs|py|java|kt|rb|cs|cpp|c|h|hpp|swift|toml|json|tf)$|\.straymark/' | sort -u) + +if [ -z "$declared" ]; then + echo "WARN: no files extracted from §Files to modify in $CHARTER_FILE" >&2 + echo " Either the section is missing, the table format is unusual, or the" >&2 + echo " declared paths don't have recognized extensions. Script can't help — exit clean." >&2 + exit 0 +fi + +# Get files actually modified in the range. +modified=$(git diff --name-only "$GIT_RANGE" 2>/dev/null | sort -u) + +if [ -z "$modified" ]; then + echo "WARN: no files modified in range $GIT_RANGE — Charter may not have executed." >&2 + exit 0 +fi + +# Set diff: declared but not modified. +# +# Two wildcard forms are supported in declared paths: +# 1. Ellipsis form `prefix...suffix` — any modified file with that prefix +# satisfies the wildcard. Used historically in AILOG references like +# `.straymark/07-ai-audit/agent-logs/AILOG-...md`. +# 2. Glob form `prefix*suffix` (added fw-4.6.2): any modified file whose +# path matches the glob (`*` → `.*` regex) satisfies the wildcard. +# Used for bulk Charter declarations like `AILOG-*.md`. Reported as the +# new finding in CHARTER-04 of issue #81. +declared_omitted="" +while IFS= read -r decl; do + # 1. Ellipsis wildcard. + if [[ "$decl" == *...* ]]; then + prefix="${decl%...*}" + if echo "$modified" | grep -q "^${prefix}"; then + continue # any match satisfies the wildcard. + fi + declared_omitted+="$decl"$'\n' + continue + fi + # 2. Glob wildcard. Convert `*` → `.*` and escape `.` for the regex match. + if [[ "$decl" == *\** ]]; then + glob_re=$(printf '%s' "$decl" | sed 's/\./\\./g; s/\*/.*/g') + if echo "$modified" | grep -qE "^${glob_re}$"; then + continue + fi + declared_omitted+="$decl"$'\n' + continue + fi + # 3. Literal path. + if ! echo "$modified" | grep -qx "$decl"; then + declared_omitted+="$decl"$'\n' + fi +done <<< "$declared" +declared_omitted=$(echo "$declared_omitted" | sed '/^$/d') + +# Set diff: modified but not declared (scope expansion). +modified_extra="" +while IFS= read -r mod; do + # Allow Charter-doc and AILOG paths through without alarm — those are always + # in scope when the Charter itself or the AILOG of execution gets touched. + if [[ "$mod" == .straymark/charters/* || "$mod" == .straymark/07-ai-audit/* ]]; then + continue + fi + if ! echo "$declared" | grep -qx "$mod"; then + # Also allow if the declared list has a wildcard prefix that matches. + # Recognizes both forms: `prefix...suffix` and `prefix*suffix` (fw-4.6.2). + matched_wildcard=0 + while IFS= read -r decl; do + if [[ "$decl" == *...* ]]; then + prefix="${decl%...*}" + if [[ "$mod" == ${prefix}* ]]; then + matched_wildcard=1 + break + fi + elif [[ "$decl" == *\** ]]; then + glob_re=$(printf '%s' "$decl" | sed 's/\./\\./g; s/\*/.*/g') + if echo "$mod" | grep -qE "^${glob_re}$"; then + matched_wildcard=1 + break + fi + fi + done <<< "$declared" + if [ $matched_wildcard -eq 0 ]; then + modified_extra+="$mod"$'\n' + fi + fi +done <<< "$modified" +modified_extra=$(echo "$modified_extra" | sed '/^$/d') + +# --- Report --- + +echo "=== Charter drift check ===" +echo " Charter: $CHARTER_FILE" +echo " Range: $GIT_RANGE" +echo " Declared: $(echo "$declared" | wc -l) files" +echo " Modified: $(echo "$modified" | wc -l) files" +echo "" + +exit_code=0 + +if [ -n "$declared_omitted" ]; then + echo "WARNING: Declared in Charter but NOT modified ($(echo "$declared_omitted" | wc -l) files):" + echo "$declared_omitted" | sed 's/^/ - /' + echo "" + echo " Action: either complete the work, or document in AILOG under '## Risk'" + echo " as 'R (new, not in Charter)' explaining why this file did not need" + echo " changes (Charter was wrong, scope simplified, etc.)." + echo "" + exit_code=1 +fi + +if [ -n "$modified_extra" ]; then + echo "INFO: Modified but NOT declared ($(echo "$modified_extra" | wc -l) files, scope expansion):" + echo "$modified_extra" | sed 's/^/ - /' + echo "" + echo " Action: if intentional, document the scope expansion in AILOG." + echo " Common reasons: mock updates after interface change, generated" + echo " files (e.g. wire_gen.go), pre-existing drift fix needed to unblock work." + echo "" + # Scope expansion is informational, not a hard failure — exit_code stays. +fi + +if [ -z "$declared_omitted" ] && [ -z "$modified_extra" ]; then + echo "OK No drift detected. Charter and execution are in sync." +fi + +exit $exit_code diff --git a/.devtrail/templates/TEMPLATE-ADR.md b/.straymark/templates/TEMPLATE-ADR.md similarity index 94% rename from .devtrail/templates/TEMPLATE-ADR.md rename to .straymark/templates/TEMPLATE-ADR.md index 4283d67..c0c8c9d 100644 --- a/.devtrail/templates/TEMPLATE-ADR.md +++ b/.straymark/templates/TEMPLATE-ADR.md @@ -7,6 +7,11 @@ updated: YYYY-MM-DD agent: [agent-name-v1.0] confidence: high | medium | low review_required: true + +# --- Approval workflow (optional, fill at review time) --- +# reviewed_by: # email | github-handle | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected risk_level: medium | high | critical eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable iso_42001_clause: [] # 4 | 5 | 6 | 7 | 8 | 9 | 10 @@ -140,4 +145,4 @@ C4Context |------|--------|--------| | YYYY-MM-DD | [agent/human] | Initial creation | - + diff --git a/.devtrail/templates/TEMPLATE-AIDEC.md b/.straymark/templates/TEMPLATE-AIDEC.md similarity index 85% rename from .devtrail/templates/TEMPLATE-AIDEC.md rename to .straymark/templates/TEMPLATE-AIDEC.md index 6f22673..b5e3df2 100644 --- a/.devtrail/templates/TEMPLATE-AIDEC.md +++ b/.straymark/templates/TEMPLATE-AIDEC.md @@ -6,6 +6,11 @@ created: YYYY-MM-DD agent: [agent-name-v1.0] confidence: high | medium | low review_required: false + +# --- Approval workflow (optional, fill at review time) --- +# reviewed_by: # email | github-handle | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected risk_level: low | medium | high | critical eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable nist_genai_risks: [] # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain @@ -84,4 +89,4 @@ related: [] --- - + diff --git a/.straymark/templates/TEMPLATE-AILABEL.md b/.straymark/templates/TEMPLATE-AILABEL.md new file mode 100644 index 0000000..610c355 --- /dev/null +++ b/.straymark/templates/TEMPLATE-AILABEL.md @@ -0,0 +1,119 @@ +--- +id: AILABEL-YYYY-MM-DD-NNN +title: "[Service] GB 45438 Content Labeling Plan" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: medium +review_required: true + +# --- Approval workflow (optional, fill at review time) --- +# reviewed_by: # email | github-handle | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: medium +gb45438_applicable: true +gb45438_content_types: [] # subset of: text | image | audio | video | virtual_scene +gb45438_explicit_label_strategy: null # disclaimer | watermark | caption | audio_cue | banner +gb45438_implicit_metadata_format: null # C2PA | XMP | EXIF | custom | none +gb45438_distributor_obligations_documented: false +iso_42001_clause: [8] +tags: [china, gb45438, labeling, ai-generated-content] +related: [] +--- + +# AILABEL: [Service] GB 45438 Content Labeling Plan + +> **IMPORTANT**: This document is a DRAFT created by an AI agent. +> It requires human review and approval before deployment. +> +> Aligned with **GB 45438-2025** *Cybersecurity Technology — Labeling Method for Content Generated by Artificial Intelligence*, in force since **2025-09-01**, and the CAC *Measures for the Identification of AI-Generated (Synthetic) Content*. Both **explicit** (visible) and **implicit** (machine-readable) labeling are mandatory for in-scope services. + +## 1. Coverage by Content Type + +| Content Type | In Scope | Generation Modality | Volume | +|--------------|---------|--------------------|--------| +| Text | [Yes/No] | [LLM completion / chat / summarization / translation] | [tokens/day] | +| Image | [Yes/No] | [text-to-image / image-edit / face-swap / pose-manipulation] | [images/day] | +| Audio | [Yes/No] | [voice-clone / TTS / music-generation] | [minutes/day] | +| Video | [Yes/No] | [text-to-video / image-to-video / face-swap / pose] | [minutes/day] | +| Virtual Scene | [Yes/No] | [immersive / hyperrealistic environment] | [scenes/day] | + +## 2. Explicit Labeling (Visible Indicators) + +> Explicit labels must be perceivable by an ordinary user. The form depends on the medium. + +| Content Type | Strategy | Placement | Wording / Visual | +|--------------|---------|-----------|------------------| +| Text | [disclaimer / banner / inline tag] | [chat header / message footer] | [e.g., "本内容由人工智能生成" / "AI-generated"] | +| Image | [watermark / caption / corner badge] | [bottom-right / centered overlay] | [Logo + text + opacity] | +| Audio | [audio_cue / spoken disclosure] | [start of clip / every N seconds] | [e.g., 1-second tone + spoken "AI-generated"] | +| Video | [watermark + caption] | [persistent corner + intro frame] | [Specification] | +| Virtual Scene | [persistent banner / pre-entry notice] | [HUD / loading screen] | [Specification] | + +## 3. Implicit Labeling (Machine-Readable Metadata) + +> Per GB 45438 §5, implicit identification embeds metadata or digital watermarks in the content file headers. The minimum mandatory fields are: **content type**, **service provider name or code**, **content identification number**. + +### 3.1 Metadata Format + +- **Selected Format**: [C2PA / XMP / EXIF / custom / none] +- **Reason for Choice**: [Compatibility, persistence, ecosystem support] + +### 3.2 Mandatory Fields (must be populated for every generated artifact) + +| Field | Source / Generator | Example | +|-------|-------------------|---------| +| `content_type` | Modality dispatcher | `text` / `image` / `audio` / `video` / `virtual_scene` | +| `service_provider_code` | Internal config | [Issued by CAC after filing — see CACFILE-...] | +| `content_id` | UUIDv7 / ULID | [Unique per artifact, traceable in logs] | +| `created_at` | Server time (UTC+8) | [ISO-8601] | +| `model_reference` | MCARD link | [MCARD-YYYY-MM-DD-NNN] | + +### 3.3 Digital Watermark (encouraged) + +- [ ] Visible watermark embedded +- [ ] Invisible watermark embedded — algorithm: [DWT-DCT / SS / LSB / proprietary] +- **Persistence**: [Survives JPEG re-compression / video re-encoding / cropping] + +## 4. Persistence Across Export / Download + +| Operation | Explicit Label Persists | Implicit Metadata Persists | Notes | +|-----------|------------------------|----------------------------|-------| +| Direct download | [Yes/No] | [Yes/No] | [Format-specific] | +| Re-export from a different tool | [Yes/No] | [Yes/No] | [Risk of metadata stripping] | +| Screenshot / screen capture | [Yes/No] | [Yes/No] | [Watermark-only fallback] | +| Re-encoding | [Yes/No] | [Yes/No] | [Robust-watermark required] | + +## 5. Distributor Verification Hooks + +> Distributors and platforms must verify metadata and prominently surface a label when synthetic content is detected. + +- **Verification API exposed**: [URL or N/A] +- **Detection signal for downstream platforms**: [How they can confirm origin without sharing the model] +- **Removal of synthetic-content tags forbidden**: [Enforcement mechanism] +- **User-facing prompt when verification succeeds**: [UX pattern] + +## 6. Test Plan + +| Test | Pass Criteria | Status | +|------|--------------|--------| +| Explicit label visible across all 5 content types | [Manual review] | [Pending] | +| Implicit metadata present in 100% of sampled outputs | [Automated scan of N samples] | [Pending] | +| Label persistence after download → re-upload | [No metadata loss] | [Pending] | +| Watermark detectable after 30% JPEG re-compression | [Watermark detector accuracy ≥ X%] | [Pending] | + +## 7. Linked Artifacts + +- **MCARD**: [Model card with `gb45438_applicable: true`] +- **CACFILE**: [Algorithm filing — provides the `service_provider_code`] +- **TC260RA**: [Risk assessment classifying labeling-failure risk] +- **ETH**: [Ethical review — transparency considerations] + +## Approval + +| Approved by | Date | Decision | Conditions | +|-------------|------|----------|-----------| +| [Reviewer] | [YYYY-MM-DD] | [approved / conditional / rejected] | [Conditions if any] | + + diff --git a/.devtrail/templates/TEMPLATE-AILOG.md b/.straymark/templates/TEMPLATE-AILOG.md similarity index 78% rename from .devtrail/templates/TEMPLATE-AILOG.md rename to .straymark/templates/TEMPLATE-AILOG.md index 17dc5e3..f499b0d 100644 --- a/.devtrail/templates/TEMPLATE-AILOG.md +++ b/.straymark/templates/TEMPLATE-AILOG.md @@ -10,6 +10,9 @@ risk_level: low | medium | high | critical eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable nist_genai_risks: [] # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain iso_42001_clause: [] # 4 | 5 | 6 | 7 | 8 | 9 | 10 +# Optional China-specific fields — populate only if regional_scope includes "china": +# tc260_risk_level: not_applicable # low | medium | high | very_high | extremely_severe | not_applicable +# gb45652_training_data_compliance: false lines_changed: 0 # Auto-calculable files_modified: [] # Auto-calculable observability_scope: none # none | basic | full — set when OTel instrumentation is relevant @@ -33,6 +36,24 @@ related: [] 2. [Action 2] 3. [Action 3] +## Batch Ledger + +> Use this section for Charters that span 3+ batches or >1 day of execution. +> Update each batch entry **immediately after** its commit lands, using +> `straymark charter batch-complete `. Entries left as +> `(pending)` at Charter close cause `straymark charter drift` to fail. +> +> Omit this section entirely for single-batch or single-session AILOGs — +> `## Actions Performed` above is sufficient there. + +### Batch 1 — [name from Charter §Tasks] + +(pending) + +### Batch 2 — [name from Charter §Tasks] + +(pending) + ## Modified Files | File | Lines Changed (+/-) | Change Description | @@ -96,4 +117,4 @@ related: [] --- - + diff --git a/.straymark/templates/TEMPLATE-CACFILE.md b/.straymark/templates/TEMPLATE-CACFILE.md new file mode 100644 index 0000000..9f53428 --- /dev/null +++ b/.straymark/templates/TEMPLATE-CACFILE.md @@ -0,0 +1,122 @@ +--- +id: CACFILE-YYYY-MM-DD-NNN +title: "[Service Name] CAC Algorithm Filing" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: medium +review_required: true + +# --- Approval workflow (optional, fill at review time) --- +# reviewed_by: # email | github-handle | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: high +cac_filing_required: true +cac_filing_type: algorithm # algorithm | generative_ai | dual +cac_filing_status: pending # pending | provincial_submitted | provincial_approved | national_submitted | national_approved | rejected | not_required +cac_filing_number: null # populated upon successful filing — format: e.g., "网信算备XXXXXXXXXXXX" +cac_provincial_authority: null # provincial CAC office handling the filing +cac_national_decision_date: null # YYYY-MM-DD when national CAC published the decision +iso_42001_clause: [8] +tags: [china, cac, algorithm-filing] +related: [] +--- + +# CACFILE: [Service Name] CAC Algorithm Filing + +> **IMPORTANT**: This document is a DRAFT created by an AI agent. +> It requires human review by counsel and the responsible compliance officer before any submission to the Cyberspace Administration of China. +> +> CAC algorithm filing is required for any externally facing service with **public-opinion attributes** or **social-mobilization capabilities** under the *Provisions on the Administration of Algorithmic Recommendations of Internet Information Services* and the *Interim Measures for the Management of Generative AI Services*. Generative AI large models additionally require a **dual filing**: provincial security assessment + national algorithm filing. + +## Service Overview + +- **Service Name**: [Customer-facing name] +- **Provider Legal Entity**: [Registered company / branch in mainland China] +- **Provider Form**: [internet information service / app / mini-program / API / other] +- **Application Domain**: [content recommendation / search ranking / personalization / generative AI / synthesis / other] +- **Algorithm Type**: [generation_synthesis / personalized_push / sequence_scheduling / search_filter / dispatch_decision] +- **Target Audience**: [General public / specific industry / minors / other] +- **Applicable Scenarios**: [Concrete use cases] + +## Public-Opinion / Social-Mobilization Attribute Assessment + +Per CAC guidance, services with these attributes must file. Document the assessment: + +- [ ] Generates / synthesizes / disseminates content viewable by the public +- [ ] Influences user opinion through ranking, recommendation, or content selection +- [ ] Capable of mobilizing users for collective action +- [ ] Operates in news, social media, audio/video, or live streaming domain + +**Conclusion**: [Required / Not required] — [Justification] + +## Training Data Description + +- **Data Sources**: [Public corpora / proprietary / licensed third-party / user-generated] +- **Data Volume**: [Approximate token / image / sample count] +- **Geographic Origin**: [Domestic / overseas / mixed — note PIPL cross-border implications] +- **Lawfulness of Sources**: [Demonstrate per Art. 7 of the Interim Measures for GenAI Services: lawfulness, accuracy, objectivity, diversity] +- **Personal Information in Training Data**: [Yes/No — if yes, link to PIPIA-XXXX] +- **Sensitive Categories Filtered**: [Methods used to remove sensitive data per PIPL Art. 28] + +## Blocked Keywords Strategy + +> Per the Interim Measures, providers must prevent generation of content that subverts state power, incites separatism, undermines national unity, promotes terrorism / extremism / ethnic hatred / discrimination, violence, or obscene content. + +- **Keyword List Source**: [Reference: internal list, version, last update] +- **Update Cadence**: [How often the list is reviewed] +- **Layered Controls**: [Pre-prompt filtering / post-generation filtering / response refusal / safe completion] +- **Audit Sample**: [Path to representative sample retained for filing] + +## Testing Question Set + +- **Test Set Size**: [Number of red-team prompts] +- **Coverage**: [Categories tested: political sensitivity, violence, self-harm, hate, discrimination, privacy, minors, etc.] +- **Pass Threshold**: [Required pass rate] +- **Latest Test Result**: [Date / Pass rate / Document reference] + +## Internal Algorithm Management Policy + +- **Designated Responsible Person**: [Name / role with full Chinese-language credentials] +- **Internal Review Workflow**: [Pre-deployment review steps] +- **Complaint Handling**: [User complaint channel + SLA] +- **Logging & Traceability**: [How model inputs/outputs are logged for accountability] + +## Algorithm Security Responsibility Report + +Per Art. 24 of the Internet Information Service Algorithm Recommendation Provisions, prepare a *Report on Implementation of Algorithm Security Responsibilities*. Outline: + +- **Algorithm Mechanism Disclosure**: [Plain-language description of how the algorithm operates] +- **User Notification**: [How users are informed of algorithmic decision-making] +- **Opt-Out Mechanism**: [How users can disable personalization] +- **Manual Intervention Capability**: [How operators override algorithmic outputs] + +## Self-Assessment + +| Risk Area | Finding | Severity | Mitigation | +|-----------|---------|----------|-----------| +| Content compliance (illegal content generation) | [Finding] | [L/M/H] | [Measure] | +| Personal information protection | [Finding] | [L/M/H] | [Measure] | +| Bias / unfair differentiated treatment | [Finding] | [L/M/H] | [Measure] | +| Intellectual property | [Finding] | [L/M/H] | [Measure] | +| Minor protection | [Finding] | [L/M/H] | [Measure] | + +## Filing Trail + +| Stage | Date | Outcome / Reference | +|-------|------|---------------------| +| Internal sign-off | [YYYY-MM-DD] | [Document reference] | +| Provincial submission | [YYYY-MM-DD] | [Receipt number] | +| Provincial decision | [YYYY-MM-DD] | [Approved / Rejected — reasons] | +| National submission | [YYYY-MM-DD] | [Receipt number] | +| National decision | [YYYY-MM-DD] | [Filing number issued] | +| Public disclosure | [YYYY-MM-DD] | [URL where the filing number is shown to end-users] | + +## Approval + +| Approved by | Date | Decision | Conditions | +|-------------|------|----------|-----------| +| [Compliance officer] | [YYYY-MM-DD] | [approved / conditional / rejected] | [Conditions if any] | + + diff --git a/.devtrail/templates/TEMPLATE-DPIA.md b/.straymark/templates/TEMPLATE-DPIA.md similarity index 82% rename from .devtrail/templates/TEMPLATE-DPIA.md rename to .straymark/templates/TEMPLATE-DPIA.md index 1313e8e..54e192a 100644 --- a/.devtrail/templates/TEMPLATE-DPIA.md +++ b/.straymark/templates/TEMPLATE-DPIA.md @@ -6,6 +6,11 @@ created: YYYY-MM-DD agent: [agent-name] confidence: low # DPIA requires extensive human judgment review_required: true # Always mandatory + +# --- Approval workflow (optional, fill at review time) --- +# reviewed_by: # email | github-handle | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected risk_level: high eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable gdpr_article_35: true # Art. 35 GDPR triggers DPIA @@ -84,6 +89,15 @@ related: [] - **Human Oversight Measures**: [Describe human-in-the-loop or human-on-the-loop mechanisms] - **Transparency to Data Subjects**: [How data subjects are informed about AI involvement in processing their data] +## Cross-reference: PIPIA (China) + +> Complete this section only if `regional_scope` includes `china` and any of the PIPL Art. 55 triggers apply (sensitive personal info, automated decision-making, third-party disclosure, cross-border transfer, public disclosure). See [PIPL-PIPIA-GUIDE.md](../00-governance/PIPL-PIPIA-GUIDE.md). +> +> When applicable, set `pipl_applicable: true` in this DPIA's frontmatter and create a companion **PIPIA-...** document. Link both documents bidirectionally via `related:`. + +- **PIPIA Reference**: [PIPIA-YYYY-MM-DD-NNN or "Not applicable — PIPL not in regional_scope"] +- **Differences vs. this DPIA**: [Brief — PIPIA-specific elements not covered above (Art. 55 trigger, retention ≥ 3 years, cross-border mechanism)] + ## Review Schedule - **Next Review Date**: [YYYY-MM-DD] @@ -94,4 +108,4 @@ related: [] - [Security incidents] - **Review Responsible**: [Role/Person responsible for conducting the review] - + diff --git a/.devtrail/templates/TEMPLATE-ETH.md b/.straymark/templates/TEMPLATE-ETH.md similarity index 87% rename from .devtrail/templates/TEMPLATE-ETH.md rename to .straymark/templates/TEMPLATE-ETH.md index 8262d1f..8014c37 100644 --- a/.devtrail/templates/TEMPLATE-ETH.md +++ b/.straymark/templates/TEMPLATE-ETH.md @@ -6,6 +6,11 @@ created: YYYY-MM-DD agent: [agent-name-v1.0] confidence: medium | low review_required: true + +# --- Approval workflow (optional, fill at review time) --- +# reviewed_by: # email | github-handle | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected risk_level: high | critical eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable nist_genai_risks: [] # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain @@ -187,6 +192,22 @@ approved_date: null --- +## TC260 Risk Mapping (China) + +> Complete this section only if `regional_scope` includes `china`. See [TC260-IMPLEMENTATION-GUIDE.md](../00-governance/TC260-IMPLEMENTATION-GUIDE.md). +> +> When a TC260RA exists for this system, summarize the resulting level here and link the document. Set `tc260_risk_level` in the frontmatter. + +| Aspect | Value | +|--------|-------| +| TC260 Risk Level | [low / medium / high / very_high / extremely_severe / not_applicable] | +| Application Scenario | [public_service / healthcare / finance / content_generation / ...] | +| Intelligence Level | [narrow / foundation / agentic / general] | +| Application Scale | [individual / organization / societal / cross_border] | +| Linked TC260RA | [TC260RA-YYYY-MM-DD-NNN or "Not applicable"] | + +--- + ## Approval | Field | Value | @@ -196,4 +217,4 @@ approved_date: null | Decision | [APPROVED/REJECTED/CONDITIONAL] | | Conditions | [If applicable] | - + diff --git a/.devtrail/templates/TEMPLATE-INC.md b/.straymark/templates/TEMPLATE-INC.md similarity index 64% rename from .devtrail/templates/TEMPLATE-INC.md rename to .straymark/templates/TEMPLATE-INC.md index b9304fa..03f7241 100644 --- a/.devtrail/templates/TEMPLATE-INC.md +++ b/.straymark/templates/TEMPLATE-INC.md @@ -6,6 +6,11 @@ created: YYYY-MM-DD agent: [agent-name-v1.0] confidence: medium review_required: true + +# --- Approval workflow (optional, fill at review time) --- +# reviewed_by: # email | github-handle | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected risk_level: high | critical severity: SEV1 | SEV2 | SEV3 | SEV4 eu_ai_act_applicable: false @@ -131,6 +136,36 @@ resolved_date: null | Authority Notified | [Yes/No/NA] | | Report Reference | [Reference number if submitted] | +## CSL 2026 Incident Reporting (China) + +> Complete this section only if `regional_scope` includes `china`. +> +> Per the **Administrative Measures for National Cybersecurity Incident Reporting** (in force 2025-11-01) and the **Cybersecurity Law amendments** (in force 2026-01-01), incidents are graded into four severity levels with the following reporting windows: +> +> | Severity | Initial report | Follow-up | Examples | +> |----------|---------------|-----------|----------| +> | `particularly_serious` | **1 hour** | 72-hour assessment + 30-day post-mortem | Government portal / critical infrastructure outage > 24h (or 6h for full-system); essential service disruption affecting > 50% of a province or > 10M people | +> | `relatively_major` | **4 hours** | 72-hour assessment + 30-day post-mortem | Data breach affecting > 1M individuals or economic loss > RMB 5M | +> | `major` | per provincial guidance | 30-day post-mortem | Significant disruption below the thresholds above | +> | `general` | per provincial guidance | — | Minor incidents | + +Set the corresponding frontmatter fields: + +```yaml +csl_severity_level: not_applicable # particularly_serious | relatively_major | major | general | not_applicable +csl_report_deadline_hours: null # 1 | 4 | 24 — coherent with severity +``` + +| Field | Value | +|-------|-------| +| CSL Severity Level | [particularly_serious / relatively_major / major / general / not_applicable] | +| Initial Report Deadline | [HH:MM UTC+8 — within 1h or 4h depending on severity] | +| Initial Report Submitted | [YYYY-MM-DD HH:MM] / [Not yet] | +| 72h Assessment Submitted | [YYYY-MM-DD] / [Pending] | +| 30-day Post-mortem Submitted | [YYYY-MM-DD] / [Pending] | +| Authority Notified | [CAC / provincial CAC / industry regulator / None] | +| Report Reference | [Filing receipt number] | + ## Open Questions 1. [Question that requires additional investigation] @@ -146,4 +181,4 @@ resolved_date: null | Review date | [YYYY-MM-DD] | | Status | [Draft/Reviewed/Closed] | - + diff --git a/.devtrail/templates/TEMPLATE-MCARD.md b/.straymark/templates/TEMPLATE-MCARD.md similarity index 78% rename from .devtrail/templates/TEMPLATE-MCARD.md rename to .straymark/templates/TEMPLATE-MCARD.md index 8097649..7312412 100644 --- a/.devtrail/templates/TEMPLATE-MCARD.md +++ b/.straymark/templates/TEMPLATE-MCARD.md @@ -6,6 +6,11 @@ created: YYYY-MM-DD agent: [agent-name] confidence: medium review_required: true + +# --- Approval workflow (optional, fill at review time) --- +# reviewed_by: # email | github-handle | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected risk_level: medium eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable nist_genai_risks: [] # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain @@ -146,6 +151,33 @@ related: [] --- +## China Regulatory Profile + +> Complete this section only if `regional_scope` in `.straymark/config.yml` includes `china`. Leave the frontmatter fields below absent or null otherwise. See [CHINA-REGULATORY-FRAMEWORK.md](../00-governance/CHINA-REGULATORY-FRAMEWORK.md) for context. + +| Aspect | Field | Linked Document | +|--------|-------|-----------------| +| TC260 v2.0 risk level | `tc260_risk_level` | TC260RA-... | +| PIPL applicability | `pipl_applicable` | PIPIA-... (if true) | +| GB 45438 content labeling | `gb45438_applicable`, `gb45438_content_types` | AILABEL-... (if applicable) | +| CAC algorithm filing | `cac_filing_required`, `cac_filing_number`, `cac_filing_status` | CACFILE-... | +| GB/T 45652 training-data security | `gb45652_training_data_compliance` | SBOM-... | + +Add these fields to the frontmatter when applicable: + +```yaml +tc260_risk_level: not_applicable # low | medium | high | very_high | extremely_severe +pipl_applicable: false +gb45438_applicable: false +gb45438_content_types: [] # text | image | audio | video | virtual_scene +cac_filing_required: false +cac_filing_number: null # populated after CAC issues the filing +cac_filing_status: not_required # pending | provincial_submitted | provincial_approved | national_submitted | national_approved | rejected | not_required +gb45652_training_data_compliance: false +``` + +--- + ## Approval | Field | Value | @@ -155,4 +187,4 @@ related: [] | Decision | [APPROVED / REJECTED / CONDITIONAL] | | Conditions | [If applicable] | - + diff --git a/.straymark/templates/TEMPLATE-PIPIA.md b/.straymark/templates/TEMPLATE-PIPIA.md new file mode 100644 index 0000000..f75d406 --- /dev/null +++ b/.straymark/templates/TEMPLATE-PIPIA.md @@ -0,0 +1,135 @@ +--- +id: PIPIA-YYYY-MM-DD-NNN +title: "[System/Process] Personal Information Protection Impact Assessment" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: low # PIPIA requires extensive human judgment +review_required: true # Always mandatory under PIPL Art. 55 + +# --- Approval workflow (optional, fill at review time) --- +# reviewed_by: # email | github-handle | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: high +pipl_applicable: true +pipl_article_55_trigger: sensitive_data # sensitive_data | automated_decision | third_party_disclosure | cross_border | public_disclosure | other +pipl_sensitive_data: true +pipl_cross_border_transfer: false +pipl_retention_until: YYYY-MM-DD # Minimum 3 years from `created` per PIPL retention requirements +iso_42001_clause: [6, 8] +dpo_consulted: false +tags: [privacy, pipl, china, pipia] +related: [] +--- + +# PIPIA: [System/Process] Personal Information Protection Impact Assessment + +> **IMPORTANT**: This document is a DRAFT created by an AI agent. +> It requires human review and approval before any processing of personal information begins. +> Per PIPL Art. 56, retain this report and the related handling-status records for **at least 3 years**. + +## Article 55 Trigger + +Mark the trigger(s) that required this PIPIA per PIPL Art. 55: + +- [ ] Processing of **sensitive personal information** (Art. 28: biometrics, religious beliefs, specific identity, medical health, financial accounts, location tracking, personal information of minors under 14, etc.) +- [ ] Use of personal information for **automated decision-making** +- [ ] **Entrusting** processing to a third party / providing data to other personal information handlers / publicly disclosing personal information +- [ ] **Cross-border transfer** of personal information +- [ ] Other processing activities with **significant impact** on individuals + +## Processing Description + +- **Nature of Processing**: [How data is collected, stored, used, and deleted] +- **Scope**: [Number of data subjects, volume, geographic scope inside/outside mainland China] +- **Context**: [Relationship with data subjects, reasonable expectations] +- **Purpose**: [Specific stated purpose] +- **Legal Basis (PIPL Art. 13)**: [consent / contract performance / legal duty / emergency / news reporting / public interest / disclosed-by-individual / other] +- **Categories of Data Subjects**: [Employees, customers, minors, patients, etc.] +- **Categories of Personal Data**: [Identifiers, contact, health, biometric, financial, location, etc.] +- **Sensitive Personal Information involved**: [Yes/No — list categories per Art. 28] +- **Recipients / Entrusted Processors**: [Who receives the data, contractual safeguards] +- **Retention Period**: [How long, deletion criteria, lawful basis for retention] + +## Necessity and Proportionality (PIPL Art. 56 §1) + +- **Lawfulness**: [Why processing is lawful under PIPL Art. 13] +- **Legitimacy**: [Why processing serves a clear, reasonable purpose] +- **Necessity**: [Why this is the minimum processing required for the purpose] +- **Purpose Limitation**: [How processing is bounded to the stated purpose] +- **Data Minimization**: [How only the minimum necessary data is collected] + +## Personal Rights Impact (PIPL Art. 56 §2) + +| Right Impacted | Likelihood | Severity | Risk Level | Mitigation | +|----------------|-----------|----------|------------|-----------| +| Right to know / decide (Art. 44) | [Low/Med/High] | [Low/Med/High] | [Low/Med/High] | [Measures] | +| Right to access / copy (Art. 45) | [Low/Med/High] | [Low/Med/High] | [Low/Med/High] | [Measures] | +| Right to correct / supplement (Art. 46) | [Low/Med/High] | [Low/Med/High] | [Low/Med/High] | [Measures] | +| Right to delete (Art. 47) | [Low/Med/High] | [Low/Med/High] | [Low/Med/High] | [Measures] | +| Right to portability (Art. 45) | [Low/Med/High] | [Low/Med/High] | [Low/Med/High] | [Measures] | +| Right to opt-out of automated decision-making (Art. 24) | [Low/Med/High] | [Low/Med/High] | [Low/Med/High] | [Measures] | + +## Security Risks (PIPL Art. 56 §2) + +| Risk | Likelihood | Severity | Risk Level | Source | Nature of Impact | +|------|-----------|----------|------------|--------|------------------| +| [Risk 1] | [L/M/H] | [L/M/H] | [L/M/H] | [Source] | [physical/material/reputational] | +| [Risk 2] | [L/M/H] | [L/M/H] | [L/M/H] | [Source] | [physical/material/reputational] | + +## Protective Measures (PIPL Art. 56 §3) + +Demonstrate that protective measures are **lawful, effective, and commensurate** with the level of risk. + +| Risk | Measure | Type | Residual Risk | Responsible | +|------|---------|------|---------------|-------------| +| [Risk 1] | [Mitigation measure] | [technical / organizational / contractual] | [L/M/H] | [Role/Person] | +| [Risk 2] | [Mitigation measure] | [technical / organizational / contractual] | [L/M/H] | [Role/Person] | + +## Cross-Border Transfer Analysis + +> Complete this section only if `pipl_cross_border_transfer: true`. +> +> Per PIPL Art. 38-40, cross-border transfer additionally requires **one** of: (a) CAC security assessment, (b) personal information protection certification, or (c) standard contract filed with provincial CAC. + +- **Destination(s)**: [Countries/regions] +- **Transfer Mechanism**: [security_assessment / certification / standard_contract / other] +- **CAC Security Review Reference**: [Filing number or N/A] +- **Necessity Justification**: [Why the data must leave mainland China] +- **Recipient Safeguards**: [Contractual obligations imposed on overseas recipient] +- **Data Subject Notification**: [How affected individuals are informed and consent obtained] + +## Automated Decision-Making (PIPL Art. 24) + +> Complete this section if processing involves automated decision-making. + +- **Decision Logic Disclosure**: [How the logic is explained to data subjects] +- **Fairness and Transparency**: [How the system is audited for unfair differentiated treatment] +- **Right to Object / Human Review**: [How individuals can request human intervention] +- **Marketing / Push Notifications**: [If used for personalized marketing, how the opt-out is provided] + +## Consultation + +- **Personal Information Protection Officer Opinion**: [Required when handler processes personal information of more than 1 million individuals — PIPL Art. 52] +- **Data Subjects Consulted**: [Yes/No] — [Methodology] +- **Provincial CAC Consulted**: [Yes/No / Not applicable] — [Reference] + +## Retention and Review + +- **PIPIA Report Retention Until**: [YYYY-MM-DD — at least 3 years from creation] +- **Next Review Date**: [YYYY-MM-DD] +- **Review Trigger Events**: + - Change in processing scope or purpose + - New categories of personal information + - Regulatory changes (PIPL amendments, CAC guidance) + - Security incidents +- **Responsible Reviewer**: [Role/Person] + +## Approval + +| Approved by | Date | Decision | Conditions | +|-------------|------|----------|-----------| +| [Reviewer] | [YYYY-MM-DD] | [approved / conditional / rejected] | [Conditions if any] | + + diff --git a/.devtrail/templates/TEMPLATE-REQ.md b/.straymark/templates/TEMPLATE-REQ.md similarity index 99% rename from .devtrail/templates/TEMPLATE-REQ.md rename to .straymark/templates/TEMPLATE-REQ.md index 8829453..59a1df1 100644 --- a/.devtrail/templates/TEMPLATE-REQ.md +++ b/.straymark/templates/TEMPLATE-REQ.md @@ -238,4 +238,4 @@ Identify who originates this requirement (per ISO/IEC/IEEE 29148:2018 §6.2): | Status | [Validated/Rejected/Modified] | | Comments | [Validator notes] | - + diff --git a/.devtrail/templates/TEMPLATE-SBOM.md b/.straymark/templates/TEMPLATE-SBOM.md similarity index 72% rename from .devtrail/templates/TEMPLATE-SBOM.md rename to .straymark/templates/TEMPLATE-SBOM.md index cd56a78..3b8afcc 100644 --- a/.devtrail/templates/TEMPLATE-SBOM.md +++ b/.straymark/templates/TEMPLATE-SBOM.md @@ -74,4 +74,19 @@ related: [] - [Monitoring activity 2: Frequency and responsible party] - [Monitoring activity 3: Frequency and responsible party] - +## GB/T 45652 Training Data Compliance (China) + +> Complete this section only if `regional_scope` includes `china`. Aligns with **GB/T 45652-2025** *Cybersecurity Technology — Security Specification for Pre-training and Fine-tuning Data of Generative AI Services* (in force 2025-11-01). +> +> Set `gb45652_training_data_compliance: true` in the frontmatter when every training-data row below is documented. + +| Dataset | Lawfulness of Source | Sensitive Personal Info Removed | Annotation Workflow Documented | Cross-border Origin? | Mitigation | +|---------|---------------------|--------------------------------|--------------------------------|----------------------|-----------| +| [Dataset 1] | [Licensed / public-domain / consent / contract] | [Yes/No — methodology] | [Yes — link / No] | [Yes / No / Mixed] | [Cross-link to PIPIA-... if cross-border] | +| [Dataset 2] | [...] | [...] | [...] | [...] | [...] | + +- **Annotation Security**: [Methods to protect annotators' personal data and prevent leakage of sensitive content during labeling] +- **Provenance Audit Cadence**: [Quarterly / annual / event-driven] +- **Linked CACFILE**: [CACFILE-... if filing required] + + diff --git a/.devtrail/templates/TEMPLATE-SEC.md b/.straymark/templates/TEMPLATE-SEC.md similarity index 96% rename from .devtrail/templates/TEMPLATE-SEC.md rename to .straymark/templates/TEMPLATE-SEC.md index 339d6ce..ec56141 100644 --- a/.devtrail/templates/TEMPLATE-SEC.md +++ b/.straymark/templates/TEMPLATE-SEC.md @@ -6,6 +6,11 @@ created: YYYY-MM-DD agent: [agent-name] confidence: medium review_required: true + +# --- Approval workflow (optional, fill at review time) --- +# reviewed_by: # email | github-handle | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected risk_level: high eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable iso_42001_clause: [6, 8] @@ -168,4 +173,4 @@ related: [] | Decision | [APPROVED / REJECTED / CONDITIONAL] | | Conditions | [If applicable] | - + diff --git a/.straymark/templates/TEMPLATE-TC260RA.md b/.straymark/templates/TEMPLATE-TC260RA.md new file mode 100644 index 0000000..b46ad08 --- /dev/null +++ b/.straymark/templates/TEMPLATE-TC260RA.md @@ -0,0 +1,148 @@ +--- +id: TC260RA-YYYY-MM-DD-NNN +title: "[System] TC260 Risk Assessment" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: medium +review_required: true + +# --- Approval workflow (optional, fill at review time) --- +# reviewed_by: # email | github-handle | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: high +tc260_application_scenario: null # e.g., public_service | healthcare | finance | content_generation | social | safety_critical +tc260_intelligence_level: null # narrow | foundation | agentic | general +tc260_application_scale: null # individual | organization | societal | cross_border +tc260_risk_level: not_applicable # low | medium | high | very_high | extremely_severe | not_applicable +tc260_endogenous_risks: [] +tc260_application_risks: [] +tc260_derivative_risks: [] +iso_42001_clause: [6] +tags: [china, tc260, risk-assessment] +related: [] +--- + +# TC260RA: [System] TC260 Risk Assessment + +> **IMPORTANT**: This document is a DRAFT created by an AI agent. +> It requires human review and approval. +> +> Aligned with the **AI Safety Governance Framework v2.0** published by TC260 (National Information Security Standardization Technical Committee, 全国信息安全标准化技术委员会) on 15 September 2025. + +## 1. Four Pillars Mapping + +Show how this system addresses each of the four pillars of the framework: + +| Pillar | Coverage in this system | +|--------|-------------------------| +| **Governance principles** (people-centered, AI for good, safe & controllable) | [Statement] | +| **Risk taxonomy** (endogenous technical / application / derivative) | [Reference to taxonomy below] | +| **Technical countermeasures** | [Reference to section 4] | +| **Governance measures** (organizational implementation) | [Reference to section 5] | + +## 2. Three-Criteria Risk Grading (Section 5.5 / Appendix 1) + +Risk level is computed from the combination of **application scenario × intelligence level × application scale**. + +### 2.1 Application Scenario + +- **Selected**: [public_service / healthcare / finance / content_generation / social / safety_critical / industrial_control / other] +- **Justification**: [Why this scenario applies] + +### 2.2 Level of Intelligence + +| Level | Definition | This system | +|-------|-----------|------------| +| Narrow | Single-purpose model | [ ] | +| Foundation | General-purpose foundation model | [ ] | +| Agentic | Autonomous agent with tool use | [ ] | +| General | Approaching AGI | [ ] | + +- **Selected**: [narrow / foundation / agentic / general] + +### 2.3 Application Scale + +| Scale | Definition | This system | +|-------|-----------|------------| +| Individual | Single-user or small team | [ ] | +| Organization | Single organization deployment | [ ] | +| Societal | Affects significant portion of public | [ ] | +| Cross-border | Operates across mainland China and other jurisdictions | [ ] | + +- **Selected**: [individual / organization / societal / cross_border] + +### 2.4 Resulting Risk Level + +| Risk Level | Description | +|------------|-------------| +| Low | Minimal expected harm; standard controls suffice | +| Medium | Foreseeable, contained harm; review and basic countermeasures required | +| High | Significant risk to individuals or specific groups; comprehensive controls required | +| Very High | Risk to societal stability or large populations; sector-level oversight | +| Extremely Severe | Risk of catastrophic or systemic harm; loss of control / catastrophic risk concerns | + +- **Computed Level**: [low / medium / high / very_high / extremely_severe] +- **Justification**: [Reasoning combining scenario × intelligence × scale] + +## 3. Risk Taxonomy + +### 3.1 Endogenous Technical Risks + +> Risks arising from the AI model itself: vulnerabilities, bias, hallucination, robustness gaps. + +| Risk | Description | Likelihood | Severity | Mitigation | +|------|-------------|-----------|----------|-----------| +| [Risk 1] | [Description] | [L/M/H] | [L/M/H] | [Measure] | +| [Risk 2] | [Description] | [L/M/H] | [L/M/H] | [Measure] | + +### 3.2 Application Risks + +> Risks arising from how the AI is technically applied: misuse, scope creep, dependency. + +| Risk | Description | Likelihood | Severity | Mitigation | +|------|-------------|-----------|----------|-----------| +| [Risk 1] | [Description] | [L/M/H] | [L/M/H] | [Measure] | +| [Risk 2] | [Description] | [L/M/H] | [L/M/H] | [Measure] | + +### 3.3 Derivative Risks + +> Risks arising from second-order societal effects: labor displacement, opinion shaping, ecosystem disruption. + +| Risk | Description | Likelihood | Severity | Mitigation | +|------|-------------|-----------|----------|-----------| +| [Risk 1] | [Description] | [L/M/H] | [L/M/H] | [Measure] | +| [Risk 2] | [Description] | [L/M/H] | [L/M/H] | [Measure] | + +## 4. Technical Countermeasures + +Map each prioritized risk to one or more technical controls (red-teaming, alignment, content filters, watermarking per GB 45438, model evaluation suites, sandboxing, etc.). + +| Risk ID | Countermeasure | Owner | Verification | +|---------|---------------|-------|-------------| +| [E.1] | [Control] | [Role] | [Test plan / metric] | +| [A.1] | [Control] | [Role] | [Test plan / metric] | +| [D.1] | [Control] | [Role] | [Test plan / metric] | + +## 5. Governance Measures + +- **Designated Owner**: [Role / Person] +- **Internal Reporting Cadence**: [Monthly / quarterly] +- **Escalation Path**: [To whom and under what triggers] +- **Open-Source Components**: [If the system embeds open-source AI: governance per v2.0 OSS clauses] +- **Catastrophic-Risk Watch**: [Required for very_high / extremely_severe levels: how loss-of-control scenarios are monitored] + +## 6. Monitoring & Review + +- **Next Review Date**: [YYYY-MM-DD] +- **Review Triggers**: [Model version change / scenario expansion / scale jump / regulatory update] +- **Linked Documents**: [ETH-..., MCARD-..., AILABEL-..., CACFILE-...] + +## Approval + +| Approved by | Date | Decision | Conditions | +|-------------|------|----------|-----------| +| [Reviewer] | [YYYY-MM-DD] | [approved / conditional / rejected] | [Conditions if any] | + + diff --git a/.devtrail/templates/TEMPLATE-TDE.md b/.straymark/templates/TEMPLATE-TDE.md similarity index 67% rename from .devtrail/templates/TEMPLATE-TDE.md rename to .straymark/templates/TEMPLATE-TDE.md index 96bbaae..dd122c9 100644 --- a/.devtrail/templates/TEMPLATE-TDE.md +++ b/.straymark/templates/TEMPLATE-TDE.md @@ -1,7 +1,7 @@ --- id: TDE-YYYY-MM-DD-NNN title: [Technical debt title] -status: identified +status: identified # `identified` → `resolved` when the debt is paid (TDE-only terminal) created: YYYY-MM-DD agent: [agent-name-v1.0] confidence: high | medium | low @@ -15,11 +15,14 @@ tags: [] related: [] priority: null assigned_to: null +promoted_from_followup: null # FU-NNN if promoted from .straymark/follow-ups-backlog.md --- # TDE: [Technical Debt Title] > **IDENTIFIED BY AGENT**: Prioritization and assignment require human decision. +> +> **Activation triggers** (any one suffices — file as `R (new, not in Charter)` in an AILOG instead if none apply): heritage from a prior Charter, applies to multiple modules/Charters, requires a dedicated Charter outside the current scope envelope, or requires human prioritization/assignment the agent cannot decide alone. See `.straymark/00-governance/AGENT-RULES.md` §3 for the full disambiguation. ## Summary @@ -121,4 +124,23 @@ Impact │ │ │ | Assigned to | [Team/Person] | | Comments | [Notes] | - +--- + +## Resolution + +> Fill this section AND flip `status: identified → resolved` in the frontmatter when +> the debt described here has been addressed. Keep the document on disk — `resolved` +> is the canonical TDE terminal state; the file becomes audit history rather than +> being deleted. See DOCUMENTATION-POLICY.md §3 for the lifecycle semantics. +> +> Omit this section entirely while the debt is still `identified` / `accepted` / +> superseded — it is meaningful only at the terminal transition. + +| Field | Value | +|-------|-------| +| Resolved by | [Charter ID / PR / commit that paid the debt] | +| Date | [YYYY-MM-DD] | +| Verification | [How was the resolution verified — tests, drift check, audit, etc.] | +| Notes | [Anything future readers should know, e.g. partial-resolution scope] | + + diff --git a/.devtrail/templates/TEMPLATE-TES.md b/.straymark/templates/TEMPLATE-TES.md similarity index 98% rename from .devtrail/templates/TEMPLATE-TES.md rename to .straymark/templates/TEMPLATE-TES.md index 21d132e..548970c 100644 --- a/.devtrail/templates/TEMPLATE-TES.md +++ b/.straymark/templates/TEMPLATE-TES.md @@ -20,7 +20,7 @@ related: [] > **Standard alignment**: ISO/IEC/IEEE 29119-3:2021 (Software Testing — Test Documentation) > > This template corresponds to the **Test Plan** level in the ISO 29119-3 hierarchy: -> - **Organizational Test Policy** — Organization-wide testing principles (out of DevTrail scope) +> - **Organizational Test Policy** — Organization-wide testing principles (out of StrayMark scope) > - **Test Strategy** — Project-level testing strategy (may be referenced in project governance) > - **Test Plan** — This document: specific test planning for a feature, component, or change @@ -198,4 +198,4 @@ related: [] | Date | [YYYY-MM-DD] | | Comments | [Notes] | - + diff --git a/.straymark/templates/charter/charter-telemetry-template.yaml b/.straymark/templates/charter/charter-telemetry-template.yaml new file mode 100644 index 0000000..a55fa5f --- /dev/null +++ b/.straymark/templates/charter/charter-telemetry-template.yaml @@ -0,0 +1,154 @@ +# StrayMark Charter telemetry — fill at Charter close. +# +# Schema: .straymark/schemas/charter-telemetry.schema.v0.json +# Conceptual: Propuesta/straymark-charter-telemetry.md (in the upstream repo) +# Storage path: .straymark/charters/CHARTER-NN.telemetry.yaml +# +# Fill time target: 5-10 minutes per Charter. The point is signal, not exhaustiveness — +# leave a field blank or omit it if you don't have honest data for it. Honest gaps +# are more useful than invented numbers. + +charter_telemetry: + # ---------- Identification ---------- + charter_id: "CHARTER-NN" # match the charter_id of the Charter file + charter_title: "" + closed_at: "YYYY-MM-DD" # date of the closing commit / merge + + # ---------- Origin & activation ---------- + # Which AILOGs (if any) motivated this Charter, and were they still useful when + # execution actually happened? still_relevant_at_execution captures whether the + # AILOG content lined up with reality, not whether it merely existed. + originating_ailogs: + - ailog_id: "AILOG-YYYY-MM-DD-NNN" + still_relevant_at_execution: true # bool + relevance_notes: "" # optional — explain partial / shifted relevance + + # The trigger as declared in the Charter, plus what actually fired the Charter + # in practice. Sentinel found that declared triggers tend to be prescriptive + # (when SHOULD this run) while the effective trigger was usually meta — the + # delta between the two is the interesting datum. + trigger: + declared_kind: "" # event_trigger | date | metric_threshold | infrastructure_milestone + declared_description: "" + fired_at: "YYYY-MM-DD" + fire_clarity: "" # clear | ambiguous | manually_decided + fire_clarity_notes: "" + + # ---------- Pre-work ---------- + # Whether the Charter's §Pre-trabajo section did its job. If items_discovered_during_planning + # is high, the field is not protecting you — flag it. + pre_work: + items_declared: 0 + items_completed_before_planning: 0 + items_skipped: 0 + items_discovered_during_planning: 0 + pre_work_quality: "" # high | medium | low + pre_work_notes: "" + + # ---------- Planning session (if any) ---------- + # Many Charters execute without a formal planning session. If so, set occurred:false + # and skip the rest of this block. + planning_session: + occurred: false + duration_minutes: 0 + participants: 0 + decisions_made: 0 + decisions_deferred: 0 + notes: "" + + # ---------- Effort ---------- + # TIME only. Sentinel's data showed lines-changed is not predictive (1.0x to 8.1x drift); + # do NOT attempt to capture it. Estimation is one of the questions this telemetry exists + # to answer. + effort: + started_at: "YYYY-MM-DD" + finished_at: "YYYY-MM-DD" + estimated_effort: "M (~1.5h)" # XS/S/M/L bucket + optional ~time + actual_effort: "M (~1.5h)" + estimation_drift_factor: 1.0 # actual / estimated TIME ratio + estimation_drift_reason: "" + + # ---------- Agent quality during execution ---------- + # r_n_plus_one_emergent_count is the field most worth your time: risks named + # during execution that weren't in §Risks. Sentinel validated this as the + # cross-agent signal of disciplined execution. + agent_quality: + sessions_count: 0 + hallucinations_caught: 0 + hallucination_categories: [] + decisions_contradicting_prior_adrs: 0 + contradiction_notes: "" + context_loaded_was_sufficient: true + additional_context_loaded_manually: 0 + r_n_plus_one_emergent_count: 0 + skill_prompts_used: [] + + # ---------- External audit ---------- + # ARRAY, not a single object — dual-audit (e.g. Copilot + Gemini) gives you + # cross-model calibration. The categorization DELTA between auditors is signal: + # if Copilot calls something "implementation_gap" and Gemini calls the same + # finding "false_positive", that disagreement is itself useful data. + external_audit: + - auditor: "" + findings_total: 0 + findings_by_category: + hallucination: 0 + implementation_gap: 0 + real_debt: 0 + false_positive: 0 + audit_quality: "" # high | medium | low (your judgment as the calibrator) + audit_notes: "" + + # ---------- Outcome & follow-ups ---------- + # scope_change_notes uses F1...FN encoding consistent with claude-analisis output. + # Optional category suffix: IG (implementation gap), FP (false positive), HALL (hallucination). + # Example: "F1 (IG): handler.go declared but not modified — scope simplified mid-flight." + outcome: + completed_as_planned: true + scope_changes: "ninguno" # ninguno | menor | mayor + scope_change_notes: "" + new_followups_generated: 0 + new_charters_created: 0 + charters_invalidated: 0 + associated_stage_id: "" + + # ---------- Pre-declare SpecKit refresh (optional) ---------- + # Populate this block ONLY if this Charter was preceded by a SpecKit refresh PR + # per the Charter-chain-evolution pattern (see + # .straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md Pattern 1). Omit the block + # entirely if the refresh did not apply — absence means "pattern not used". + # Use `straymark charter refresh-suggest ` to check the heuristic. + # pre_declare_refresh: + # enabled: true + # refresh_pr: "owner/repo#76" + # refresh_aidec: "AIDEC-YYYY-MM-DD-NNN-slug" + # reusable_patterns_integrated: 0 + # code_gaps_integrated: 0 + # discipline_patterns_integrated: 0 + # empirical_corrections_integrated: 0 + # operator_decisions_ratified: 0 + + # ---------- Post-close audit-driven amendment (optional) ---------- + # Populate this block ONLY if this Charter received a Batch N.4 amendment AFTER + # `status: closed` (e.g. external audit findings remediated on the same execute + # branch). See .straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md Pattern 2. + # `straymark charter amend ` scaffolds the amendment and emits this block. + # post_close_amendment: + # applied: true + # trigger: "external_audit" # external_audit | production_incident | deferred_implementation + # ailog_id: "AILOG-YYYY-MM-DD-NNN" # the NEW AILOG that documents the amendment + # findings_closed: 0 + # files_modified: 0 + # effort_hours: 0.0 + + # ---------- Qualitative (where insight usually lives) ---------- + # Quantitative fields tell you what happened; qualitative tells you what to change. + # The format_iteration field is part of the self-evolving feedback loop: each + # Charter refines the format of the next. + qualitative: + format_iteration: "v4" + friction_points: [] + wins: [] + overall_satisfaction: 0 # 1-5 + would_repeat_format: true + proposed_format_changes: "" diff --git a/.straymark/templates/charter/charter-template.md b/.straymark/templates/charter/charter-template.md new file mode 100644 index 0000000..4775938 --- /dev/null +++ b/.straymark/templates/charter/charter-template.md @@ -0,0 +1,232 @@ +--- +charter_id: CHARTER-NN +status: declared +effort_estimate: M +trigger: "[1-line: what concrete signal — observable event, declared decision, metric threshold, or infrastructure milestone — justifies executing this Charter now]" +# Exactly one of the following two should be set when the Charter has a known origin. +# Both absent is valid for a Charter scaffolded without an explicit origin (must be +# filled before status moves to in-progress). +# originating_ailogs: [AILOG-YYYY-MM-DD-NNN] +# originating_spec: specs/001-feature/spec.md +--- + +# Charter: [BRIEF TITLE] + +> **Status (mirrored from frontmatter — source of truth is above):** declared. Effort: [XS | S | M | L] (~[N] min). +> +> **Origin:** [human-readable summary; the machine-readable form is `originating_ailogs` or `originating_spec` in frontmatter]. + + + +## Context + +[1-2 paragraphs. What problem this Charter solves, what operational or regulatory +motivation makes it urgent, what has been attempted before (if anything). Cite the +originating AILOGs here too if it helps the reader understand why the work was deferred.] + +## Scope + +**In scope:** + +[Numbered list of concrete changes to apply. Each item must be verifiable: "X file +gains Y method", "Z test covers W case". Avoid vague items like "improve performance" +— those are objectives, not scope.] + +1. [Item 1] +2. [Item 2] +3. [...] + +**Out of scope:** + +[List of things explicitly NOT covered by this Charter. Important so external auditors +do not classify them as gaps. Ideally cite the Charter or initiative where they belong.] + +- [Item 1] — deferred to [Charter/initiative]. +- [Item 2] — out of scope because [reason]. + +## Files to modify + +| File | Change | +|---|---| +| `path/to/file.ext` | [Concrete description of the change] | +| `...` | `...` | +| `.straymark/07-ai-audit/agent-logs/AILOG-...md` | New, `risk_level: [low|medium|high]` | + +## Verification + +### Local checks + +Commands executable literal in a clean shell — include explicit setup of dependencies. +Any failure of these commands indicates real debt. + +```bash +# Build & test (adapt to your stack) + + + +# Security/vulnerability scanners with explicit setup +# (Pattern validated in Sentinel PLAN-01..05: implicit PATH lookups generated +# false-positive 'real_debt' classifications from external auditors.) + + + +# Other local commands here. If they require integration infra, document explicitly: + +``` + +### Production smoke (after deploy) + +Commands that **only apply after deploy to a real environment**. NOT executable in a +clean shell without infrastructure. External auditors should skip this section — +failures here are NOT `real_debt`. + +```bash +# Example: verify a new endpoint is live in production. +TOKEN="$( print-identity-token)" +curl -X PUT "https://${SERVICE_HOST}/api/v1/.../..." \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"...": "..."}' + +# Example: SQL query in production DB to verify event persistence. + connect -- \ + -c "SELECT context FROM audit_records WHERE action='...' \ + ORDER BY timestamp DESC LIMIT 1" +``` + +## Risks + +[List of risks R1, R2, ... that the implementation commits to mitigate. Each with its +mitigation documented. Convention: if a NEW risk emerges during execution that was not +anticipated, document it in the AILOG under `## Risk` as `R (new, not in Charter)` +— Gemini and other external auditors validate these cross-document. + +Each mitigation should specify: (a) concrete trigger or threshold (no "eventually"), +(b) action committed, (c) what happens if the mitigation itself fails, (d) where +follow-up insights are captured if the risk surfaces lessons for a later cycle.] + +- **R1 — [risk description]**: [probability/severity]. + Mitigation: [concrete action taken in implementation]. +- **R2 — ...**: ... +- [...] + +## Tasks + +1. Sync main, branch `/[slug]`. +2. [Implementation task 1]. +3. [Implementation task 2]. +4. [...] +5. AILOG (`risk_level: [low|medium|high]`, `review_required: [true|false]`). +6. **For multi-batch execution (3+ batches or >1 day)**: maintain a + `## Batch Ledger` in the AILOG. After each batch commit, run + `straymark charter batch-complete ` to update the + ledger before pushing. The drift gate at close will reject any + `### Batch N` left as `(pending)`. Skip this step for single-batch + Charters — `## Actions Performed` in the AILOG suffices. + *Note*: if audit findings arrive **after** `status: closed` and warrant + a bounded code-level fix, see STRAYMARK.md §15.B (post-close Batch N.4 + amendment) and `straymark charter amend` instead of opening a new Charter. +7. Local verification passes clean. +8. **Auto-checklist drift** (when Phase 2 of the CLI roadmap ships): + `straymark charter drift CHARTER-NN ` to detect drifts between declared + and modified files **before** commit. If it reports omissions, complete the work + or document in the AILOG under `## Risk` as `R (new, not in Charter)`. If it + reports scope expansion, document in the AILOG the reason (mock updates, generated + files, drift fix pre-existing, etc.). Until Phase 2 ships, run Sentinel's + `check-plan-drift.sh` manually for the same effect. +9. Commit + push + open PR. + +## Charter Closure + +When closing this Charter: + +1. **Atomic update (format v4)**: if the drift check (Tasks #7) reported any drift + not already captured in the AILOG, edit `## Files to modify` and/or add a + `## Closing notes` block in **this same commit/PR**, before submitting. Do not + defer to a post-merge housekeeping PR. The atomic-update pattern is the canonical + way to keep the Charter coherent with execution; deferring it leaves the Charter + stale and confuses future readers (PLAN-07 of Sentinel demonstrated the failure + mode that this step prevents). + +2. **Post-merge drift check** (automated when Phase 2 ships + manual review): + - Run `straymark charter drift CHARTER-NN origin/main..HEAD` (Phase 2) or the + equivalent Sentinel script, and validate the output is clean or that all + drifts are documented in the AILOG. + - This catches the rare case where drift is introduced post-merge (squash + mangling, admin amendments, etc.) and the atomic step in #1 could not apply. + +3. **Move the row** in `.straymark/charters/README.md` to `## Closed` and reference the PR. + +4. **Status frontmatter** moves from `in-progress` to `closed` (and optionally + `closed_at: YYYY-MM-DD` is added — the schema allows arbitrary additional fields). + +5. **Do not delete** this file — the planning history matters as much as the AILOG + of execution. + +## Closing notes + +> Add this section ONLY when Tasks #7 drift check reported drift that the +> implementer chose to remediate atomically (rather than redoing the implementation +> to match `## Files to modify` exactly). Each bullet: what changed vs declaration, +> why, reference to the AILOG that documented the decision. Omit the section +> entirely if no drift was detected — empty `## Closing notes` is noise. +> +> Historical examples in Sentinel: PLAN-05 (`docs/plans/05-per-service-anomaly-thresholds.md`) +> §Notas de cierre — files removed because the implementation chose a different +> injection point; PLAN-07 (`docs/plans/07-fix-distribution-aligner.md`) §Notas de +> cierre — file removed because the live test was agnostic to the change. Both +> demonstrate the pattern in production usage. + +- `[path/file-from-declaration.ext]` [removed | relocated to X | repurposed]: + [1-2 lines explaining what the implementation did instead and why the original + declaration is no longer accurate]. Reference: AILOG-YYYY-MM-DD-NNN §[section]. + +--- + + diff --git a/.straymark/templates/charter/i18n/es/charter-template.md b/.straymark/templates/charter/i18n/es/charter-template.md new file mode 100644 index 0000000..063ef56 --- /dev/null +++ b/.straymark/templates/charter/i18n/es/charter-template.md @@ -0,0 +1,233 @@ +--- +charter_id: CHARTER-NN +status: declared +effort_estimate: M +trigger: "[1 línea: qué señal concreta — evento observable, decisión declarada, umbral métrico, o hito de infraestructura — justifica ejecutar este Charter ahora]" +# Establece exactamente uno de los siguientes dos cuando el Charter tenga un origen conocido. +# Ambos ausentes es válido para un Charter creado sin origen explícito (debe llenarse antes +# de que el status pase a in-progress). +# originating_ailogs: [AILOG-YYYY-MM-DD-NNN] +# originating_spec: specs/001-feature/spec.md +--- + +# Charter: [TÍTULO BREVE] + +> **Status (espejado del frontmatter — la fuente de verdad está arriba):** declared. Esfuerzo: [XS | S | M | L] (~[N] min). +> +> **Origen:** [resumen humano; la forma machine-readable es `originating_ailogs` u `originating_spec` en el frontmatter]. + + + +## Context + +[1-2 párrafos. Qué problema resuelve este Charter, qué motivación operacional o +regulatoria lo hace urgente, qué se ha intentado antes (si algo). Cita los AILOGs +origen aquí también si ayuda al lector a entender por qué la deuda quedó abierta.] + +## Scope + +**In scope:** + +[Lista numerada de los cambios concretos a aplicar. Cada item debe ser verificable: +"X archivo gana Y método", "Z test cubre W caso". Evitar items vagos como "mejorar +performance" — esos son objetivos, no scope.] + +1. [Item 1] +2. [Item 2] +3. [...] + +**Out of scope:** + +[Lista de cosas explícitamente NO cubiertas por este Charter. Importante para que +auditores no las clasifiquen como gaps. Idealmente cita el Charter o iniciativa +donde sí van.] + +- [Item 1] — diferido a [Charter/iniciativa]. +- [Item 2] — fuera del alcance porque [razón]. + +## Archivos a modificar + +| Archivo | Cambio | +|---|---| +| `path/al/archivo.ext` | [Descripción concreta del cambio] | +| `...` | `...` | +| `.straymark/07-ai-audit/agent-logs/AILOG-...md` | Nuevo, `risk_level: [low|medium|high]` | + +## Verification + +### Local checks + +Comandos ejecutables literal en clean shell — incluyen setup explícito de dependencias. +Cualquier fallo de estos comandos indica deuda real. + +```bash +# Build & test (adapta a tu stack) + + + +# Setup explícito de scanners de seguridad/vulnerabilidades +# (Patrón validado en Sentinel PLAN-01..05: lookups implícitos en PATH generaban +# clasificaciones falso-positivas como 'real_debt' por auditores externos.) + + + +# Otros comandos locales aquí. Si requieren infra de integración, indicar: + +``` + +### Production smoke (after deploy) + +Comandos que **solo aplican después de deploy a un ambiente real**. NO ejecutables +en clean shell sin infraestructura. Auditores externos deben saltar esta sección — +fallos aquí no son `real_debt`. + +```bash +# Ejemplo: verificar que un endpoint nuevo está vivo en producción. +TOKEN="$( print-identity-token)" +curl -X PUT "https://${SERVICE_HOST}/api/v1/.../..." \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"...": "..."}' + +# Ejemplo: query SQL en DB productiva para verificar evento persistido. + connect -- \ + -c "SELECT context FROM audit_records WHERE action='...' \ + ORDER BY timestamp DESC LIMIT 1" +``` + +## Riesgos + +[Lista de riesgos R1, R2, ... que la implementación se compromete a mitigar. Cada uno +con su mitigación documentada. Convención: si durante la ejecución emerge un riesgo +NUEVO no anticipado, documentarlo en el AILOG bajo `## Risk` como +`R (nuevo, no en Charter)` — Gemini y otros auditores externos validan estos +cross-document. + +Cada mitigación debe especificar: (a) trigger o threshold concreto (no "eventualmente"), +(b) acción comprometida, (c) qué pasa si la mitigación misma falla, (d) dónde se +captura el follow-up si el riesgo destapa lecciones para un ciclo posterior.] + +- **R1 — [descripción del riesgo]**: [probabilidad/severidad]. + Mitigación: [acción concreta tomada en la implementación]. +- **R2 — ...**: ... +- [...] + +## Tasks + +1. Sync main, branch `/[slug]`. +2. [Tarea de implementación 1]. +3. [Tarea de implementación 2]. +4. [...] +5. AILOG (`risk_level: [low|medium|high]`, `review_required: [true|false]`). +6. **Para ejecución multi-batch (3+ lotes o >1 día)**: mantener una + `## Batch Ledger` en el AILOG. Después de cada commit de lote, correr + `straymark charter batch-complete ` para actualizar + la bitácora antes de pushear. El drift gate al cierre rechazará + cualquier `### Batch N` que quede como `(pending)`. Saltar este paso + en Charters de un solo lote — `## Acciones Realizadas` en el AILOG basta. +7. Verification local pasa limpio. +8. **Auto-checklist drift** (cuando entregue Fase 2 del CLI roadmap): + `straymark charter drift CHARTER-NN ` para detectar drifts entre lo declarado + y lo modificado **antes** del commit. Si reporta omisiones, completar el trabajo + o documentar en AILOG bajo `## Risk` como `R (nuevo, no en Charter)`. Si + reporta scope expansion, documentar en AILOG el motivo (mock updates, generated + files, drift fix pre-existente, etc.). Hasta que Fase 2 entregue, correr el + `check-plan-drift.sh` de Sentinel manualmente para el mismo efecto. +9. Commit + push + abrir PR. + +## Cierre del Charter + +Al cerrar este Charter: + +1. **Atomic update (format v4)**: si el drift check (Tasks #7) reportó cualquier drift + no capturado ya en el AILOG, editar `## Archivos a modificar` y/o añadir un bloque + `## Closing notes` en **este mismo commit/PR**, antes de submitir. No diferir a un + housekeeping PR post-merge. El patrón atomic-update es la forma canónica de mantener + el Charter coherente con la ejecución; diferirlo deja el Charter stale y confunde a + lectores futuros (PLAN-07 de Sentinel demostró el failure mode que este step previene). + +2. **Post-merge drift check** (automatizado cuando entregue Fase 2 + revisión manual): + - Correr `straymark charter drift CHARTER-NN origin/main..HEAD` (Fase 2) o el + script de Sentinel equivalente, y validar que el output esté limpio o que + todos los drifts estén documentados en el AILOG. + - Esto atrapa el caso raro donde drift se introduce post-merge (squash mangling, + amendments admin, etc.) y el step atomic en #1 no pudo aplicar. + +3. **Mover la fila** en `.straymark/charters/README.md` a `## Cerrados` y referenciar el PR. + +4. **Status del frontmatter** pasa de `in-progress` a `closed` (y opcionalmente + se añade `closed_at: YYYY-MM-DD` — el schema permite campos adicionales arbitrarios). + +5. **No borrar** este archivo — el historial de planning importa tanto como el AILOG + de ejecución. + +## Closing notes + +> Añadir esta sección SOLO cuando el drift check (Tasks #7) reportó drift que el +> implementor eligió remediar atómicamente (en lugar de rehacer la implementación +> para coincidir con `## Archivos a modificar` exactamente). Cada bullet: qué cambió +> respecto a la declaración, por qué, referencia al AILOG que documentó la decisión. +> Omitir la sección entera si no hubo drift — un `## Closing notes` vacío es ruido. +> +> Ejemplos históricos en Sentinel: PLAN-05 (`docs/plans/05-per-service-anomaly-thresholds.md`) +> §Notas de cierre — archivos removidos porque la implementación eligió otro punto +> de inyección; PLAN-07 (`docs/plans/07-fix-distribution-aligner.md`) §Notas de +> cierre — archivo removido porque el live test resultó agnóstico al cambio. Ambos +> demuestran el patrón en uso productivo. + +- `[path/archivo-de-declaración.ext]` [removido | reubicado a X | repurposed]: + [1-2 líneas explicando qué hizo la implementación en lugar de eso y por qué la + declaración original ya no es precisa]. Referencia: AILOG-YYYY-MM-DD-NNN §[sección]. + +--- + + diff --git a/.straymark/templates/charter/i18n/zh-CN/charter-template.md b/.straymark/templates/charter/i18n/zh-CN/charter-template.md new file mode 100644 index 0000000..6784430 --- /dev/null +++ b/.straymark/templates/charter/i18n/zh-CN/charter-template.md @@ -0,0 +1,217 @@ +--- +charter_id: CHARTER-NN +status: declared +effort_estimate: M +trigger: "[一行：哪个具体信号 — 可观察的事件、声明的决策、指标阈值或基础设施里程碑 — 证明现在执行此 Charter 是合理的]" +# 当 Charter 有已知的来源时，以下两个字段应恰好设置其中一个。 +# 对于在没有明确来源的情况下搭建的 Charter，两者都不存在是有效的（在状态 +# 转为 in-progress 之前必须填写）。 +# originating_ailogs: [AILOG-YYYY-MM-DD-NNN] +# originating_spec: specs/001-feature/spec.md +--- + +# Charter: [简短标题] + +> **状态（从 frontmatter 映射 — 真实来源在上方）:** declared. 工作量: [XS | S | M | L] (~[N] 分钟). +> +> **来源:** [人类可读的摘要；机器可读的形式是 frontmatter 中的 `originating_ailogs` 或 `originating_spec`]. + + + +## 背景 + +[1-2 段。此 Charter 解决什么问题，是什么操作或监管动机使其紧迫，之前尝试过什么（如果有）。 +如果有助于读者理解为什么推迟该工作，也可在此引用原始 AILOGs。] + +## 范围 + +**范围内:** + +[要应用的具体变更的编号列表。每一项都必须可验证："X 文件 +增加 Y 方法"、"Z 测试覆盖 W 情况"。避免诸如"改善性能"之类的模糊条目 +— 那些是目标，不是范围。] + +1. [项目 1] +2. [项目 2] +3. [...] + +**范围外:** + +[明确不被此 Charter 涵盖的内容列表。重要的是，这样外部审计员就不会将其 +分类为差距。理想情况下，引用它们所属的 Charter 或倡议。] + +- [项目 1] — 推迟到 [Charter/倡议]. +- [项目 2] — 因 [原因] 不在范围内. + +## 要修改的文件 + +| 文件 | 变更 | +|---|---| +| `path/to/file.ext` | [变更的具体描述] | +| `...` | `...` | +| `.straymark/07-ai-audit/agent-logs/AILOG-...md` | 新建, `risk_level: [low|medium|high]` | + +## 验证 + +### 本地检查 + +可在干净 shell 中按字面执行的命令 — 包含依赖项的显式安装。 +这些命令的任何失败都表明真实的债务。 + +```bash +# 构建与测试（适应你的技术栈） + + + +# 带有显式安装的安全/漏洞扫描器 +# （在 Sentinel PLAN-01..05 中验证的模式：隐式 PATH 查找产生 +# 来自外部审计员的误报 'real_debt' 分类。） + + + +# 其他本地命令。如果它们需要集成基础设施，请显式记录： + +``` + +### 生产环境冒烟测试（部署后） + +**仅在部署到真实环境后才适用的命令**。在没有基础设施的干净 shell 中 +**不可执行**。外部审计员应跳过本节 — 此处的失败**不是** `real_debt`。 + +```bash +# 示例：验证生产环境中新端点是否上线。 +TOKEN="$( print-identity-token)" +curl -X PUT "https://${SERVICE_HOST}/api/v1/.../..." \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"...": "..."}' + +# 示例：在生产数据库中执行 SQL 查询以验证事件持久化。 + connect -- \ + -c "SELECT context FROM audit_records WHERE action='...' \ + ORDER BY timestamp DESC LIMIT 1" +``` + +## 风险 + +[R1, R2, ... 风险列表，实现承诺要缓解。每项都附有缓解措施文档。约定： +如果在执行过程中出现 Charter 中未预见的新风险，则在 AILOG 的 `## Risk` +下记录为 `R (new, not in Charter)` — Gemini 和其他外部审计员 +进行跨文档验证。 + +每项缓解措施都应说明：(a) 具体的触发条件或阈值（不要"最终"）， +(b) 承诺的行动，(c) 如果缓解措施本身失败会发生什么，(d) 如果风险揭示 +了未来周期的经验教训，则在何处记录后续洞察。] + +- **R1 — [风险描述]**: [概率/严重性]. + 缓解措施: [在实现中采取的具体行动]. +- **R2 — ...**: ... +- [...] + +## 任务 + +1. 同步 main，创建分支 `/[slug]`. +2. [实现任务 1]. +3. [实现任务 2]. +4. [...] +5. AILOG (`risk_level: [low|medium|high]`, `review_required: [true|false]`). +6. **对于多批次执行（3+ 批次或 >1 天）**：在 AILOG 中维护 + `## Batch Ledger`（批次台账）。每个批次的 commit 之后，运行 + `straymark charter batch-complete ` 在推送前更新 + 台账。关闭时的 drift gate 将拒绝任何仍为 `(pending)` 的 + `### Batch N`。对于单批次 Charter，请跳过此步骤——AILOG 中的 + `## 执行的操作` 已足够。 +7. 本地验证通过且干净. +8. **自动检查清单漂移**（当 CLI 路线图的第 2 阶段发布时）： + `straymark charter drift CHARTER-NN ` 在提交**之前**检测声明的文件 + 与修改的文件之间的漂移。如果它报告遗漏，请完成工作或在 AILOG 的 + `## Risk` 下记录为 `R (new, not in Charter)`。如果它报告范围扩展， + 请在 AILOG 中记录原因（mock 更新、生成的文件、漂移修复预先存在等）。 + 在第 2 阶段发布之前，手动运行 Sentinel 的 `check-plan-drift.sh` 以获得相同效果。 +9. 提交 + 推送 + 打开 PR. + +## Charter 关闭 + +关闭此 Charter 时： + +1. **原子更新（格式 v4）**: 如果漂移检查（任务 #7）报告了任何 + AILOG 中尚未捕获的漂移，请在提交前在**同一提交/PR**中编辑 + `## 要修改的文件` 和/或添加 `## 关闭说明` 块。不要推迟到合并后的 + 维护 PR。原子更新模式是保持 Charter 与执行一致的规范方式；推迟它 + 会使 Charter 变得陈旧，并使未来的读者感到困惑（Sentinel 的 PLAN-07 + 演示了此步骤所防止的失败模式）。 + +2. **合并后漂移检查**（第 2 阶段发布时自动化 + 手动审查）： + - 运行 `straymark charter drift CHARTER-NN origin/main..HEAD`（第 2 阶段）或 + 等效的 Sentinel 脚本，并验证输出是干净的，或所有 + 漂移都已在 AILOG 中记录。 + - 这捕获了在合并后引入漂移的罕见情况（squash 改写、管理员修订等）， + 而 #1 中的原子步骤无法应用。 + +3. **将 `.straymark/charters/README.md` 中的行移动**到 `## Closed` 并引用 PR. + +4. **状态 frontmatter** 从 `in-progress` 移动到 `closed`（并可选地 + 添加 `closed_at: YYYY-MM-DD` — schema 允许任意附加字段）. + +5. **不要删除**此文件 — 规划历史与执行的 AILOG 一样重要. + +## 关闭说明 + +> 仅当任务 #7 漂移检查报告了实现者选择原子地补救（而不是重做实现 +> 以完全匹配 `## 要修改的文件`）的漂移时，才添加此部分。每个要点： +> 相对于声明发生了什么变化，为什么，引用记录决策的 AILOG。如果未检测到 +> 漂移，则完全省略该部分 — 空的 `## 关闭说明` 是噪声。 +> +> Sentinel 中的历史示例：PLAN-05 (`docs/plans/05-per-service-anomaly-thresholds.md`) +> §关闭说明 — 文件被移除，因为实现选择了不同的注入点；PLAN-07 +> (`docs/plans/07-fix-distribution-aligner.md`) §关闭说明 — 文件被移除，因为 +> 实时测试对此变更不敏感。两者都演示了在生产使用中的模式。 + +- `[path/file-from-declaration.ext]` [已移除 | 重定位到 X | 重新用途化]: + [1-2 行解释实现做了什么以及为什么原始声明不再准确]。 + 引用: AILOG-YYYY-MM-DD-NNN §[section]. + +--- + + diff --git a/.devtrail/templates/i18n/es/TEMPLATE-ADR.md b/.straymark/templates/i18n/es/TEMPLATE-ADR.md similarity index 94% rename from .devtrail/templates/i18n/es/TEMPLATE-ADR.md rename to .straymark/templates/i18n/es/TEMPLATE-ADR.md index 3cb30be..c0bbaa2 100644 --- a/.devtrail/templates/i18n/es/TEMPLATE-ADR.md +++ b/.straymark/templates/i18n/es/TEMPLATE-ADR.md @@ -7,6 +7,11 @@ updated: YYYY-MM-DD agent: [agent-name-v1.0] confidence: high | medium | low review_required: true + +# --- Workflow de aprobación (opcional, llenar al momento de la revisión) --- +# reviewed_by: # email | usuario-github | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected risk_level: medium | high | critical eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable iso_42001_clause: [] # 4 | 5 | 6 | 7 | 8 | 9 | 10 @@ -140,4 +145,4 @@ C4Context |-------|-------|--------| | YYYY-MM-DD | [agente/humano] | Creación inicial | - + diff --git a/.devtrail/templates/i18n/es/TEMPLATE-AIDEC.md b/.straymark/templates/i18n/es/TEMPLATE-AIDEC.md similarity index 84% rename from .devtrail/templates/i18n/es/TEMPLATE-AIDEC.md rename to .straymark/templates/i18n/es/TEMPLATE-AIDEC.md index 1915110..36a60b5 100644 --- a/.devtrail/templates/i18n/es/TEMPLATE-AIDEC.md +++ b/.straymark/templates/i18n/es/TEMPLATE-AIDEC.md @@ -6,6 +6,11 @@ created: YYYY-MM-DD agent: [agent-name-v1.0] confidence: high | medium | low review_required: false + +# --- Workflow de aprobación (opcional, llenar al momento de la revisión) --- +# reviewed_by: # email | usuario-github | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected risk_level: low | medium | high | critical eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable nist_genai_risks: [] # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain @@ -84,4 +89,4 @@ related: [] --- - + diff --git a/.straymark/templates/i18n/es/TEMPLATE-AILABEL.md b/.straymark/templates/i18n/es/TEMPLATE-AILABEL.md new file mode 100644 index 0000000..5f14e41 --- /dev/null +++ b/.straymark/templates/i18n/es/TEMPLATE-AILABEL.md @@ -0,0 +1,118 @@ +--- +id: AILABEL-YYYY-MM-DD-NNN +title: "[Servicio] Plan de Etiquetado de Contenido GB 45438" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: medium +review_required: true + +# --- Workflow de aprobación (opcional, llenar al momento de la revisión) --- +# reviewed_by: # email | usuario-github | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: medium +gb45438_applicable: true +gb45438_content_types: [] # subset of: text | image | audio | video | virtual_scene +gb45438_explicit_label_strategy: null # disclaimer | watermark | caption | audio_cue | banner +gb45438_implicit_metadata_format: null # C2PA | XMP | EXIF | custom | none +gb45438_distributor_obligations_documented: false +iso_42001_clause: [8] +tags: [china, gb45438, labeling, ai-generated-content] +related: [] +--- + +# AILABEL: [Servicio] Plan de Etiquetado de Contenido GB 45438 + +> **IMPORTANTE**: Borrador creado por un agente de IA. Requiere revisión y aprobación humana antes del despliegue. +> +> Alineado con **GB 45438-2025** *Cybersecurity Technology — Labeling Method for Content Generated by Artificial Intelligence*, en vigor desde el **2025-09-01**, y las *Measures for the Identification of AI-Generated (Synthetic) Content* del CAC. Tanto el etiquetado **explícito** (visible) como el **implícito** (legible por máquina) son obligatorios. + +## 1. Cobertura por Tipo de Contenido + +| Tipo | En alcance | Modalidad de generación | Volumen | +|------|----------|------------------------|---------| +| Texto | [Sí/No] | [LLM / chat / resumen / traducción] | [tokens/día] | +| Imagen | [Sí/No] | [text-to-image / edición / face-swap / poses] | [imágenes/día] | +| Audio | [Sí/No] | [voice-clone / TTS / generación de música] | [minutos/día] | +| Vídeo | [Sí/No] | [text-to-video / image-to-video / face-swap / poses] | [minutos/día] | +| Escena virtual | [Sí/No] | [inmersivo / hiperrealista] | [escenas/día] | + +## 2. Etiquetado Explícito (Indicadores Visibles) + +> Los marcadores explícitos deben ser perceptibles por un usuario común. La forma depende del medio. + +| Tipo | Estrategia | Ubicación | Texto / Visual | +|------|-----------|-----------|----------------| +| Texto | [disclaimer / banner / etiqueta inline] | [encabezado / pie de mensaje] | [ej: "本内容由人工智能生成" / "Generado por IA"] | +| Imagen | [watermark / caption / corner badge] | [esquina inferior derecha / overlay] | [Logo + texto + opacidad] | +| Audio | [audio_cue / disclosure hablado] | [inicio de clip / cada N s] | [Tono 1s + locución "Generado por IA"] | +| Vídeo | [watermark + caption] | [esquina persistente + frame inicial] | [Especificación] | +| Escena virtual | [banner persistente / aviso pre-entrada] | [HUD / pantalla de carga] | [Especificación] | + +## 3. Etiquetado Implícito (Metadata Legible por Máquina) + +> Per GB 45438 §5, la identificación implícita embebe metadatos o marcas de agua en cabeceras. Campos **mínimos obligatorios**: **tipo de contenido**, **nombre/código del proveedor**, **número de identificación del contenido**. + +### 3.1 Formato de Metadata + +- **Formato seleccionado**: [C2PA / XMP / EXIF / custom / none] +- **Razón**: [Compatibilidad, persistencia, soporte de ecosistema] + +### 3.2 Campos Obligatorios (cada artefacto generado) + +| Campo | Origen | Ejemplo | +|-------|--------|---------| +| `content_type` | Despachador de modalidad | `text` / `image` / `audio` / `video` / `virtual_scene` | +| `service_provider_code` | Configuración interna | [Emitido por CAC tras registro — ver CACFILE-...] | +| `content_id` | UUIDv7 / ULID | [Único por artefacto, trazable en logs] | +| `created_at` | Hora servidor (UTC+8) | [ISO-8601] | +| `model_reference` | Enlace MCARD | [MCARD-YYYY-MM-DD-NNN] | + +### 3.3 Marca de Agua Digital (recomendado) + +- [ ] Marca de agua visible embebida +- [ ] Marca de agua invisible embebida — algoritmo: [DWT-DCT / SS / LSB / propietario] +- **Persistencia**: [Sobrevive recompresión JPEG / re-codificación de vídeo / recortes] + +## 4. Persistencia ante Exportación / Descarga + +| Operación | Etiqueta explícita persiste | Metadata implícita persiste | Notas | +|-----------|----------------------------|-----------------------------|-------| +| Descarga directa | [Sí/No] | [Sí/No] | [Específico al formato] | +| Re-exportación con otra herramienta | [Sí/No] | [Sí/No] | [Riesgo de stripping] | +| Captura de pantalla | [Sí/No] | [Sí/No] | [Solo watermark de respaldo] | +| Re-codificación | [Sí/No] | [Sí/No] | [Marca de agua robusta requerida] | + +## 5. Hooks de Verificación para Distribuidores + +> Los distribuidores y plataformas deben verificar metadatos y mostrar prominentemente una etiqueta cuando se identifica contenido sintético. + +- **API de verificación expuesta**: [URL o N/A] +- **Señal de detección para plataformas downstream**: [Cómo confirman origen sin compartir el modelo] +- **Prohibido remover etiquetas de contenido sintético**: [Mecanismo de enforcement] +- **Prompt al usuario en verificación exitosa**: [Patrón UX] + +## 6. Plan de Pruebas + +| Prueba | Criterio | Estado | +|--------|---------|--------| +| Etiqueta explícita visible en los 5 tipos | [Revisión manual] | [Pendiente] | +| Metadata implícita en 100% de outputs muestreados | [Escaneo automatizado de N] | [Pendiente] | +| Persistencia de etiqueta tras descarga → re-subida | [Sin pérdida de metadata] | [Pendiente] | +| Marca de agua detectable tras 30% recompresión JPEG | [Precisión ≥ X%] | [Pendiente] | + +## 7. Artefactos Vinculados + +- **MCARD**: [Model card con `gb45438_applicable: true`] +- **CACFILE**: [Algorithm filing — provee `service_provider_code`] +- **TC260RA**: [Risk assessment — riesgo de fallo de etiquetado] +- **ETH**: [Ethical review — consideraciones de transparencia] + +## Aprobación + +| Aprobado por | Fecha | Decisión | Condiciones | +|--------------|-------|----------|-------------| +| [Revisor] | [YYYY-MM-DD] | [aprobado / condicional / rechazado] | [Si aplica] | + + diff --git a/.devtrail/templates/i18n/es/TEMPLATE-AILOG.md b/.straymark/templates/i18n/es/TEMPLATE-AILOG.md similarity index 82% rename from .devtrail/templates/i18n/es/TEMPLATE-AILOG.md rename to .straymark/templates/i18n/es/TEMPLATE-AILOG.md index 8de1c1d..78a37fb 100644 --- a/.devtrail/templates/i18n/es/TEMPLATE-AILOG.md +++ b/.straymark/templates/i18n/es/TEMPLATE-AILOG.md @@ -33,6 +33,25 @@ related: [] 2. [Acción 2] 3. [Acción 3] +## Bitácora por Lote (Batch Ledger) + +> Usa esta sección para Charters que abarquen 3+ lotes o >1 día de ejecución. +> Actualiza cada entrada **inmediatamente después** de que aterriza su commit, +> usando `straymark charter batch-complete `. Las entradas +> que queden como `(pending)` al cierre del Charter hacen fallar +> `straymark charter drift`. +> +> Omite esta sección por completo para AILOGs de un solo lote o sesión — +> `## Acciones Realizadas` arriba es suficiente en ese caso. + +### Batch 1 — [nombre desde §Tasks del Charter] + +(pending) + +### Batch 2 — [nombre desde §Tasks del Charter] + +(pending) + ## Archivos Modificados | Archivo | Líneas Cambiadas (+/-) | Descripción del Cambio | @@ -96,4 +115,4 @@ related: [] --- - + diff --git a/.straymark/templates/i18n/es/TEMPLATE-CACFILE.md b/.straymark/templates/i18n/es/TEMPLATE-CACFILE.md new file mode 100644 index 0000000..62b7a65 --- /dev/null +++ b/.straymark/templates/i18n/es/TEMPLATE-CACFILE.md @@ -0,0 +1,121 @@ +--- +id: CACFILE-YYYY-MM-DD-NNN +title: "[Nombre del Servicio] Registro de Algoritmo CAC" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: medium +review_required: true + +# --- Workflow de aprobación (opcional, llenar al momento de la revisión) --- +# reviewed_by: # email | usuario-github | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: high +cac_filing_required: true +cac_filing_type: algorithm # algorithm | generative_ai | dual +cac_filing_status: pending # pending | provincial_submitted | provincial_approved | national_submitted | national_approved | rejected | not_required +cac_filing_number: null # se rellena tras registro exitoso +cac_provincial_authority: null +cac_national_decision_date: null +iso_42001_clause: [8] +tags: [china, cac, algorithm-filing] +related: [] +--- + +# CACFILE: [Nombre del Servicio] Registro de Algoritmo CAC + +> **IMPORTANTE**: Este documento es un BORRADOR creado por un agente de IA. Requiere revisión por parte del equipo legal y del responsable de cumplimiento antes de cualquier presentación a la Cyberspace Administration of China. +> +> El registro de algoritmo CAC es obligatorio para servicios externos con **atributos de opinión pública** o **capacidad de movilización social**. Los modelos generativos requieren además **doble registro**: evaluación de seguridad provincial + registro de algoritmo nacional. + +## Resumen del Servicio + +- **Nombre del servicio**: [Nombre orientado al usuario] +- **Entidad legal proveedora**: [Empresa registrada en China continental] +- **Forma del servicio**: [servicio de información en internet / app / mini-program / API / otro] +- **Dominio de aplicación**: [recomendación / búsqueda / personalización / IA generativa / síntesis / otro] +- **Tipo de algoritmo**: [generation_synthesis / personalized_push / sequence_scheduling / search_filter / dispatch_decision] +- **Audiencia objetivo**: [Público / industria específica / menores / otro] +- **Escenarios aplicables**: [Casos de uso concretos] + +## Evaluación de Atributos de Opinión Pública / Movilización Social + +Por orientación CAC, los servicios con estos atributos deben registrarse: + +- [ ] Genera / sintetiza / disemina contenido visible al público +- [ ] Influye en la opinión vía ranking, recomendación o selección +- [ ] Capaz de movilizar usuarios para acción colectiva +- [ ] Opera en noticias, redes sociales, audio/vídeo, streaming en vivo + +**Conclusión**: [Requerido / No requerido] — [Justificación] + +## Descripción de los Datos de Entrenamiento + +- **Fuentes**: [Corpus público / propietario / licenciado / generado por usuarios] +- **Volumen**: [tokens / imágenes / muestras aproximadas] +- **Origen geográfico**: [Doméstico / extranjero / mixto — implicaciones PIPL] +- **Legalidad de fuentes**: [Per Art. 7 Medidas Provisionales: legalidad, exactitud, objetividad, diversidad] +- **Información personal en datos de entrenamiento**: [Sí/No — vincular PIPIA-XXXX] +- **Categorías sensibles filtradas**: [Métodos para remover datos sensibles per PIPL Art. 28] + +## Estrategia de Palabras Clave Bloqueadas + +> Las Medidas Provisionales obligan a impedir contenido que subvierta el poder estatal, incite al separatismo, socave la unidad nacional, promueva terrorismo / extremismo / odio étnico / discriminación, violencia o contenido obsceno. + +- **Fuente de la lista**: [Lista interna, versión, actualización] +- **Cadencia de actualización**: [Frecuencia de revisión] +- **Controles por capas**: [Filtrado pre-prompt / post-generación / rechazo de respuesta / safe completion] +- **Muestra de auditoría**: [Ruta a la muestra retenida] + +## Conjunto de Preguntas de Prueba + +- **Tamaño**: [Número de prompts de red-team] +- **Cobertura**: [Categorías: sensibilidad política, violencia, autolesiones, odio, discriminación, privacidad, menores] +- **Umbral de aprobación**: [Tasa de aprobación requerida] +- **Último resultado**: [Fecha / tasa / referencia documental] + +## Política Interna de Gestión de Algoritmos + +- **Responsable designado**: [Nombre / rol con credenciales en chino] +- **Flujo de revisión interna**: [Pasos pre-despliegue] +- **Manejo de quejas**: [Canal + SLA] +- **Logging y trazabilidad**: [Cómo se registran entradas/salidas del modelo] + +## Reporte de Responsabilidad de Seguridad del Algoritmo + +Per Art. 24 de las Disposiciones de Recomendación Algorítmica: + +- **Divulgación del mecanismo**: [Descripción accesible] +- **Notificación al usuario**: [Cómo se informa de la decisión algorítmica] +- **Mecanismo de opt-out**: [Cómo desactivar la personalización] +- **Capacidad de intervención manual**: [Cómo se anula el output algorítmico] + +## Auto-evaluación + +| Área de Riesgo | Hallazgo | Severidad | Mitigación | +|---------------|----------|-----------|-----------| +| Cumplimiento de contenido | [Hallazgo] | [B/M/A] | [Medida] | +| Protección de información personal | [Hallazgo] | [B/M/A] | [Medida] | +| Sesgo / trato diferenciado injusto | [Hallazgo] | [B/M/A] | [Medida] | +| Propiedad intelectual | [Hallazgo] | [B/M/A] | [Medida] | +| Protección de menores | [Hallazgo] | [B/M/A] | [Medida] | + +## Trazabilidad del Registro + +| Etapa | Fecha | Resultado / Referencia | +|-------|-------|------------------------| +| Sign-off interno | [YYYY-MM-DD] | [Referencia] | +| Presentación provincial | [YYYY-MM-DD] | [Número de recibo] | +| Decisión provincial | [YYYY-MM-DD] | [Aprobado / Rechazado — razones] | +| Presentación nacional | [YYYY-MM-DD] | [Número de recibo] | +| Decisión nacional | [YYYY-MM-DD] | [Número de filing emitido] | +| Divulgación pública | [YYYY-MM-DD] | [URL donde se muestra el filing al usuario final] | + +## Aprobación + +| Aprobado por | Fecha | Decisión | Condiciones | +|--------------|-------|----------|-------------| +| [Compliance officer] | [YYYY-MM-DD] | [aprobado / condicional / rechazado] | [Si aplica] | + + diff --git a/.devtrail/templates/i18n/es/TEMPLATE-DPIA.md b/.straymark/templates/i18n/es/TEMPLATE-DPIA.md similarity index 94% rename from .devtrail/templates/i18n/es/TEMPLATE-DPIA.md rename to .straymark/templates/i18n/es/TEMPLATE-DPIA.md index a6e3aff..fa537d9 100644 --- a/.devtrail/templates/i18n/es/TEMPLATE-DPIA.md +++ b/.straymark/templates/i18n/es/TEMPLATE-DPIA.md @@ -6,6 +6,11 @@ created: YYYY-MM-DD agent: [agent-name] confidence: low # La DPIA requiere juicio humano extenso review_required: true # Siempre obligatorio + +# --- Workflow de aprobación (opcional, llenar al momento de la revisión) --- +# reviewed_by: # email | usuario-github | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected risk_level: high eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable gdpr_article_35: true # Art. 35 RGPD activa la DPIA @@ -94,4 +99,4 @@ related: [] - [Incidentes de seguridad] - **Responsable de la Revisión**: [Rol/Persona responsable de realizar la revisión] - + diff --git a/.devtrail/templates/i18n/es/TEMPLATE-ETH.md b/.straymark/templates/i18n/es/TEMPLATE-ETH.md similarity index 96% rename from .devtrail/templates/i18n/es/TEMPLATE-ETH.md rename to .straymark/templates/i18n/es/TEMPLATE-ETH.md index b13e2ff..c2dc856 100644 --- a/.devtrail/templates/i18n/es/TEMPLATE-ETH.md +++ b/.straymark/templates/i18n/es/TEMPLATE-ETH.md @@ -6,6 +6,11 @@ created: YYYY-MM-DD agent: [agent-name-v1.0] confidence: medium | low review_required: true + +# --- Workflow de aprobación (opcional, llenar al momento de la revisión) --- +# reviewed_by: # email | usuario-github | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected risk_level: high | critical eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable nist_genai_risks: [] # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain @@ -196,4 +201,4 @@ approved_date: null | Decisión | [APROBADO/RECHAZADO/CONDICIONAL] | | Condiciones | [Si aplica] | - + diff --git a/.devtrail/templates/i18n/es/TEMPLATE-INC.md b/.straymark/templates/i18n/es/TEMPLATE-INC.md similarity index 93% rename from .devtrail/templates/i18n/es/TEMPLATE-INC.md rename to .straymark/templates/i18n/es/TEMPLATE-INC.md index d88b8bd..c1e6cde 100644 --- a/.devtrail/templates/i18n/es/TEMPLATE-INC.md +++ b/.straymark/templates/i18n/es/TEMPLATE-INC.md @@ -6,6 +6,11 @@ created: YYYY-MM-DD agent: [agent-name-v1.0] confidence: medium review_required: true + +# --- Workflow de aprobación (opcional, llenar al momento de la revisión) --- +# reviewed_by: # email | usuario-github | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected risk_level: high | critical severity: SEV1 | SEV2 | SEV3 | SEV4 eu_ai_act_applicable: false @@ -146,4 +151,4 @@ resolved_date: null | Fecha de revisión | [YYYY-MM-DD] | | Estado | [Borrador/Revisado/Cerrado] | - + diff --git a/.devtrail/templates/i18n/es/TEMPLATE-MCARD.md b/.straymark/templates/i18n/es/TEMPLATE-MCARD.md similarity index 95% rename from .devtrail/templates/i18n/es/TEMPLATE-MCARD.md rename to .straymark/templates/i18n/es/TEMPLATE-MCARD.md index cbc4df6..9894c52 100644 --- a/.devtrail/templates/i18n/es/TEMPLATE-MCARD.md +++ b/.straymark/templates/i18n/es/TEMPLATE-MCARD.md @@ -6,6 +6,11 @@ created: YYYY-MM-DD agent: [agent-name] confidence: medium review_required: true + +# --- Workflow de aprobación (opcional, llenar al momento de la revisión) --- +# reviewed_by: # email | usuario-github | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected risk_level: medium eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable nist_genai_risks: [] # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain @@ -155,4 +160,4 @@ related: [] | Decisión | [APROBADO / RECHAZADO / CONDICIONAL] | | Condiciones | [Si aplica] | - + diff --git a/.straymark/templates/i18n/es/TEMPLATE-PIPIA.md b/.straymark/templates/i18n/es/TEMPLATE-PIPIA.md new file mode 100644 index 0000000..265fee0 --- /dev/null +++ b/.straymark/templates/i18n/es/TEMPLATE-PIPIA.md @@ -0,0 +1,132 @@ +--- +id: PIPIA-YYYY-MM-DD-NNN +title: "[Sistema/Proceso] Evaluación de Impacto de Protección de Información Personal" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: low # PIPIA requiere amplio juicio humano +review_required: true # Obligatorio bajo PIPL Art. 55 + +# --- Workflow de aprobación (opcional, llenar al momento de la revisión) --- +# reviewed_by: # email | usuario-github | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: high +pipl_applicable: true +pipl_article_55_trigger: sensitive_data # sensitive_data | automated_decision | third_party_disclosure | cross_border | public_disclosure | other +pipl_sensitive_data: true +pipl_cross_border_transfer: false +pipl_retention_until: YYYY-MM-DD # Mínimo 3 años desde `created` por PIPL +iso_42001_clause: [6, 8] +dpo_consulted: false +tags: [privacy, pipl, china, pipia] +related: [] +--- + +# PIPIA: [Sistema/Proceso] Evaluación de Impacto de Protección de Información Personal + +> **IMPORTANTE**: Este documento es un BORRADOR creado por un agente de IA. Requiere revisión y aprobación humana antes de iniciar cualquier procesamiento de información personal. +> Por PIPL Art. 56, este informe y los registros de procesamiento relacionados deben conservarse **al menos 3 años**. + +## Activador del Artículo 55 + +Marque los activadores que motivaron este PIPIA según PIPL Art. 55: + +- [ ] Procesamiento de **información personal sensible** (Art. 28: biometría, creencias religiosas, identidad específica, salud, cuentas financieras, geolocalización, datos de menores de 14 años) +- [ ] Uso de información personal para **toma de decisiones automatizada** +- [ ] **Encargo** de procesamiento a terceros / provisión a otros responsables / divulgación pública +- [ ] **Transferencia transfronteriza** de información personal +- [ ] Otras actividades de procesamiento con **impacto significativo** sobre los individuos + +## Descripción del Procesamiento + +- **Naturaleza**: [Cómo se recopilan, almacenan, usan y eliminan los datos] +- **Alcance**: [Número de titulares, volumen, alcance geográfico dentro/fuera de China continental] +- **Contexto**: [Relación con los titulares, expectativas razonables] +- **Propósito**: [Propósito específico declarado] +- **Base legal (PIPL Art. 13)**: [consentimiento / ejecución contractual / deber legal / emergencia / informes periodísticos / interés público / información publicada / otra] +- **Categorías de titulares**: [Empleados, clientes, menores, pacientes, etc.] +- **Categorías de datos personales**: [Identificadores, contacto, salud, biometría, financieros, ubicación, etc.] +- **Información personal sensible involucrada**: [Sí/No — listar categorías Art. 28] +- **Destinatarios / encargados**: [Quién recibe los datos, salvaguardas contractuales] +- **Período de retención**: [Duración, criterios de eliminación, base legal] + +## Necesidad y Proporcionalidad (PIPL Art. 56 §1) + +- **Legalidad**: [Por qué el procesamiento es legal bajo PIPL Art. 13] +- **Legitimidad**: [Propósito claro y razonable] +- **Necesidad**: [Procesamiento mínimo necesario para el propósito] +- **Limitación de propósito**: [Cómo se limita al propósito declarado] +- **Minimización de datos**: [Cómo se recopila solo el mínimo necesario] + +## Impacto sobre Derechos Personales (PIPL Art. 56 §2) + +| Derecho impactado | Probabilidad | Severidad | Nivel de riesgo | Mitigación | +|-------------------|-------------|-----------|----------------|-----------| +| Derecho a saber / decidir (Art. 44) | [B/M/A] | [B/M/A] | [B/M/A] | [Medidas] | +| Derecho a acceder / copiar (Art. 45) | [B/M/A] | [B/M/A] | [B/M/A] | [Medidas] | +| Derecho a corregir / complementar (Art. 46) | [B/M/A] | [B/M/A] | [B/M/A] | [Medidas] | +| Derecho a eliminar (Art. 47) | [B/M/A] | [B/M/A] | [B/M/A] | [Medidas] | +| Derecho a portabilidad (Art. 45) | [B/M/A] | [B/M/A] | [B/M/A] | [Medidas] | +| Derecho a oponerse a decisión automatizada (Art. 24) | [B/M/A] | [B/M/A] | [B/M/A] | [Medidas] | + +## Riesgos de Seguridad (PIPL Art. 56 §2) + +| Riesgo | Probabilidad | Severidad | Nivel | Origen | Naturaleza del Impacto | +|--------|-------------|-----------|-------|--------|------------------------| +| [Riesgo 1] | [B/M/A] | [B/M/A] | [B/M/A] | [Origen] | [físico/material/reputacional] | + +## Medidas Protectoras (PIPL Art. 56 §3) + +Demuestre que las medidas son **legales, efectivas y proporcionales** al nivel de riesgo. + +| Riesgo | Medida | Tipo | Riesgo residual | Responsable | +|--------|--------|------|-----------------|-------------| +| [Riesgo 1] | [Medida] | [técnica / organizativa / contractual] | [B/M/A] | [Rol/Persona] | + +## Análisis de Transferencia Transfronteriza + +> Complete esta sección sólo si `pipl_cross_border_transfer: true`. +> +> Por PIPL Art. 38-40, la transferencia transfronteriza requiere **uno** de: (a) Evaluación de seguridad CAC, (b) Certificación de protección de información personal, (c) Contrato estándar archivado con CAC provincial. + +- **Destino(s)**: [Países/regiones] +- **Mecanismo**: [security_assessment / certification / standard_contract / other] +- **Referencia de revisión de seguridad CAC**: [Número o N/A] +- **Justificación de necesidad**: [Por qué los datos deben salir de China continental] +- **Salvaguardas del receptor**: [Obligaciones contractuales impuestas] +- **Notificación al titular**: [Cómo se informa y obtiene consentimiento] + +## Toma de Decisiones Automatizada (PIPL Art. 24) + +> Complete esta sección si el procesamiento involucra decisión automatizada. + +- **Divulgación de la lógica**: [Cómo se explica al titular] +- **Equidad y transparencia**: [Cómo se audita el trato diferenciado injusto] +- **Derecho a oponerse / revisión humana**: [Cómo se solicita intervención humana] +- **Marketing / push**: [Cómo se proporciona el opt-out] + +## Consultas + +- **Opinión del Oficial de Protección de Información Personal**: [Requerido si > 1.000.000 individuos — PIPL Art. 52] +- **Titulares consultados**: [Sí/No] — [Metodología] +- **CAC provincial consultado**: [Sí/No / No aplicable] — [Referencia] + +## Retención y Revisión + +- **PIPIA retenido hasta**: [YYYY-MM-DD — al menos 3 años desde la creación] +- **Próxima revisión**: [YYYY-MM-DD] +- **Eventos disparadores**: + - Cambios en alcance o propósito + - Nuevas categorías de información personal + - Cambios regulatorios (enmiendas PIPL, guía CAC) + - Incidentes de seguridad +- **Responsable de revisión**: [Rol/Persona] + +## Aprobación + +| Aprobado por | Fecha | Decisión | Condiciones | +|--------------|-------|----------|-------------| +| [Revisor] | [YYYY-MM-DD] | [aprobado / condicional / rechazado] | [Si aplica] | + + diff --git a/.devtrail/templates/i18n/es/TEMPLATE-REQ.md b/.straymark/templates/i18n/es/TEMPLATE-REQ.md similarity index 99% rename from .devtrail/templates/i18n/es/TEMPLATE-REQ.md rename to .straymark/templates/i18n/es/TEMPLATE-REQ.md index 7ff0ebe..921d863 100644 --- a/.devtrail/templates/i18n/es/TEMPLATE-REQ.md +++ b/.straymark/templates/i18n/es/TEMPLATE-REQ.md @@ -238,4 +238,4 @@ Identificar quién origina este requisito (según ISO/IEC/IEEE 29148:2018 §6.2) | Estado | [Validado/Rechazado/Modificado] | | Comentarios | [Notas del validador] | - + diff --git a/.devtrail/templates/i18n/es/TEMPLATE-SBOM.md b/.straymark/templates/i18n/es/TEMPLATE-SBOM.md similarity index 98% rename from .devtrail/templates/i18n/es/TEMPLATE-SBOM.md rename to .straymark/templates/i18n/es/TEMPLATE-SBOM.md index fbd1884..8cddbac 100644 --- a/.devtrail/templates/i18n/es/TEMPLATE-SBOM.md +++ b/.straymark/templates/i18n/es/TEMPLATE-SBOM.md @@ -74,4 +74,4 @@ related: [] - [Actividad de monitoreo 2: Frecuencia y responsable] - [Actividad de monitoreo 3: Frecuencia y responsable] - + diff --git a/.devtrail/templates/i18n/es/TEMPLATE-SEC.md b/.straymark/templates/i18n/es/TEMPLATE-SEC.md similarity index 96% rename from .devtrail/templates/i18n/es/TEMPLATE-SEC.md rename to .straymark/templates/i18n/es/TEMPLATE-SEC.md index dbb6136..df6b21a 100644 --- a/.devtrail/templates/i18n/es/TEMPLATE-SEC.md +++ b/.straymark/templates/i18n/es/TEMPLATE-SEC.md @@ -6,6 +6,11 @@ created: YYYY-MM-DD agent: [agent-name] confidence: medium review_required: true + +# --- Workflow de aprobación (opcional, llenar al momento de la revisión) --- +# reviewed_by: # email | usuario-github | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected risk_level: high eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable iso_42001_clause: [6, 8] @@ -168,4 +173,4 @@ related: [] | Decisión | [APROBADO / RECHAZADO / CONDICIONAL] | | Condiciones | [Si aplica] | - + diff --git a/.straymark/templates/i18n/es/TEMPLATE-TC260RA.md b/.straymark/templates/i18n/es/TEMPLATE-TC260RA.md new file mode 100644 index 0000000..16c42cf --- /dev/null +++ b/.straymark/templates/i18n/es/TEMPLATE-TC260RA.md @@ -0,0 +1,142 @@ +--- +id: TC260RA-YYYY-MM-DD-NNN +title: "[Sistema] Evaluación de Riesgos TC260" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: medium +review_required: true + +# --- Workflow de aprobación (opcional, llenar al momento de la revisión) --- +# reviewed_by: # email | usuario-github | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: high +tc260_application_scenario: null # ej: public_service | healthcare | finance | content_generation | social | safety_critical +tc260_intelligence_level: null # narrow | foundation | agentic | general +tc260_application_scale: null # individual | organization | societal | cross_border +tc260_risk_level: not_applicable # low | medium | high | very_high | extremely_severe | not_applicable +tc260_endogenous_risks: [] +tc260_application_risks: [] +tc260_derivative_risks: [] +iso_42001_clause: [6] +tags: [china, tc260, risk-assessment] +related: [] +--- + +# TC260RA: [Sistema] Evaluación de Riesgos TC260 + +> **IMPORTANTE**: Borrador creado por un agente de IA. Requiere revisión y aprobación humana. +> +> Alineado con el **AI Safety Governance Framework v2.0** publicado por TC260 (Comité Técnico Nacional de Estandarización de Seguridad de la Información) el 15 de septiembre de 2025. + +## 1. Mapeo a los Cuatro Pilares + +Mostrar cómo el sistema cubre cada pilar: + +| Pilar | Cobertura | +|-------|-----------| +| **Principios de gobernanza** (centrado en personas, IA para el bien, seguro y controlable) | [Declaración] | +| **Taxonomía de riesgos** (endógeno técnico / aplicación / derivado) | [Ver sección 3] | +| **Contramedidas técnicas** | [Ver sección 4] | +| **Medidas de gobernanza** (implementación organizacional) | [Ver sección 5] | + +## 2. Clasificación por Tres Criterios (Sección 5.5 / Apéndice 1) + +El nivel de riesgo se compone de **escenario de aplicación × nivel de inteligencia × escala de aplicación**. + +### 2.1 Escenario de Aplicación + +- **Seleccionado**: [public_service / healthcare / finance / content_generation / social / safety_critical / industrial_control / other] +- **Justificación**: [Por qué aplica este escenario] + +### 2.2 Nivel de Inteligencia + +| Nivel | Definición | Este sistema | +|-------|-----------|-------------| +| Narrow | Modelo de propósito único | [ ] | +| Foundation | Modelo fundacional general (LLM, visión-lenguaje) | [ ] | +| Agentic | Modelo fundacional + uso autónomo de herramientas | [ ] | +| General | Aproximándose a AGI | [ ] | + +- **Seleccionado**: [narrow / foundation / agentic / general] + +### 2.3 Escala de Aplicación + +| Escala | Definición | Este sistema | +|--------|-----------|-------------| +| Individual | Usuario único / equipo pequeño | [ ] | +| Organization | Despliegue en una sola organización | [ ] | +| Societal | Afecta a una porción significativa del público | [ ] | +| Cross-border | Opera entre China continental y otras jurisdicciones | [ ] | + +- **Seleccionado**: [individual / organization / societal / cross_border] + +### 2.4 Nivel de Riesgo Resultante + +| Nivel | Descripción | +|-------|-------------| +| Low | Daño esperado mínimo; controles estándar suficientes | +| Medium | Daño previsible y contenido; revisión y contramedidas básicas | +| High | Riesgo significativo para individuos o grupos específicos | +| Very High | Riesgo para la estabilidad social o grandes poblaciones | +| Extremely Severe | Riesgo de daño catastrófico o sistémico | + +- **Nivel computado**: [low / medium / high / very_high / extremely_severe] +- **Justificación**: [Razonamiento combinando escenario × inteligencia × escala] + +## 3. Taxonomía de Riesgos + +### 3.1 Riesgos Endógenos Técnicos + +> Inherentes al modelo: vulnerabilidades, sesgos, alucinación, robustez. + +| Riesgo | Descripción | Probabilidad | Severidad | Mitigación | +|--------|-------------|-------------|-----------|-----------| +| [Riesgo 1] | [Descripción] | [B/M/A] | [B/M/A] | [Medida] | + +### 3.2 Riesgos de Aplicación + +> De cómo se aplica técnicamente: uso indebido, scope creep, dependencia. + +| Riesgo | Descripción | Probabilidad | Severidad | Mitigación | +|--------|-------------|-------------|-----------|-----------| +| [Riesgo 1] | [Descripción] | [B/M/A] | [B/M/A] | [Medida] | + +### 3.3 Riesgos Derivados + +> Efectos sociales de segundo orden: desplazamiento laboral, modelado de opinión, disrupción del ecosistema. + +| Riesgo | Descripción | Probabilidad | Severidad | Mitigación | +|--------|-------------|-------------|-----------|-----------| +| [Riesgo 1] | [Descripción] | [B/M/A] | [B/M/A] | [Medida] | + +## 4. Contramedidas Técnicas + +| ID Riesgo | Contramedida | Responsable | Verificación | +|-----------|--------------|-------------|-------------| +| [E.1] | [Control] | [Rol] | [Test/métrica] | +| [A.1] | [Control] | [Rol] | [Test/métrica] | +| [D.1] | [Control] | [Rol] | [Test/métrica] | + +## 5. Medidas de Gobernanza + +- **Responsable designado**: [Rol / Persona] +- **Cadencia de reporte interno**: [Mensual / trimestral] +- **Ruta de escalado**: [A quién y bajo qué disparadores] +- **Componentes open-source**: [Si embebe IA OSS: gobernanza per cláusulas v2.0 OSS] +- **Vigilancia de riesgo catastrófico**: [Requerido para very_high / extremely_severe] + +## 6. Monitoreo y Revisión + +- **Próxima revisión**: [YYYY-MM-DD] +- **Disparadores**: [Cambio de versión del modelo / expansión de escenario / salto de escala / actualización regulatoria] +- **Documentos vinculados**: [ETH-..., MCARD-..., AILABEL-..., CACFILE-...] + +## Aprobación + +| Aprobado por | Fecha | Decisión | Condiciones | +|--------------|-------|----------|-------------| +| [Revisor] | [YYYY-MM-DD] | [aprobado / condicional / rechazado] | [Si aplica] | + + diff --git a/.devtrail/templates/i18n/es/TEMPLATE-TDE.md b/.straymark/templates/i18n/es/TEMPLATE-TDE.md similarity index 67% rename from .devtrail/templates/i18n/es/TEMPLATE-TDE.md rename to .straymark/templates/i18n/es/TEMPLATE-TDE.md index 9f9f495..15cdce5 100644 --- a/.devtrail/templates/i18n/es/TEMPLATE-TDE.md +++ b/.straymark/templates/i18n/es/TEMPLATE-TDE.md @@ -1,7 +1,7 @@ --- id: TDE-YYYY-MM-DD-NNN title: [Título de la deuda técnica] -status: identified +status: identified # `identified` → `resolved` cuando la deuda se paga (terminal sólo-TDE) created: YYYY-MM-DD agent: [agent-name-v1.0] confidence: high | medium | low @@ -15,11 +15,14 @@ tags: [] related: [] priority: null assigned_to: null +promoted_from_followup: null # FU-NNN si fue promovido desde .straymark/follow-ups-backlog.md --- # TDE: [Título de la Deuda Técnica] > **IDENTIFICADO POR AGENTE**: La priorización y asignación requieren decisión humana. +> +> **Triggers de activación** (basta con cualquiera — si ninguno aplica, registra como `R (new, not in Charter)` en un AILOG en su lugar): herencia de un Charter previo, aplica a múltiples módulos/Charters, requiere un Charter dedicado fuera del envelope de scope actual, o requiere priorización/asignación humana que el agente no puede decidir solo. Ver `.straymark/00-governance/AGENT-RULES.md` §3 para la desambiguación completa. ## Resumen @@ -121,4 +124,23 @@ Impacto │ │ │ | Asignado a | [Equipo/Persona] | | Comentarios | [Notas] | - +--- + +## Resolución + +> Llena esta sección Y cambia `status: identified → resolved` en el frontmatter cuando +> la deuda descrita aquí haya sido atendida. Mantén el documento en disco — `resolved` +> es el estado terminal canónico de TDE; el archivo se convierte en historia de auditoría +> en lugar de eliminarse. Ver DOCUMENTATION-POLICY.md §3 para la semántica del ciclo. +> +> Omite esta sección completamente mientras la deuda sigue `identified` / `accepted` / +> superseded — solo tiene sentido en la transición terminal. + +| Campo | Valor | +|-------|-------| +| Resuelto por | [ID del Charter / PR / commit que pagó la deuda] | +| Fecha | [YYYY-MM-DD] | +| Verificación | [Cómo se verificó la resolución — tests, drift check, audit, etc.] | +| Notas | [Cualquier cosa que los lectores futuros deban saber, p.ej. scope de resolución parcial] | + + diff --git a/.devtrail/templates/i18n/es/TEMPLATE-TES.md b/.straymark/templates/i18n/es/TEMPLATE-TES.md similarity index 98% rename from .devtrail/templates/i18n/es/TEMPLATE-TES.md rename to .straymark/templates/i18n/es/TEMPLATE-TES.md index 49df0c2..053c8c6 100644 --- a/.devtrail/templates/i18n/es/TEMPLATE-TES.md +++ b/.straymark/templates/i18n/es/TEMPLATE-TES.md @@ -20,7 +20,7 @@ related: [] > **Alineación con estándares**: ISO/IEC/IEEE 29119-3:2021 (Pruebas de Software — Documentación de Pruebas) > > Este template corresponde al nivel de **Plan de Pruebas** en la jerarquía de ISO 29119-3: -> - **Política de Pruebas Organizacional** — Principios de pruebas a nivel organización (fuera del alcance de DevTrail) +> - **Política de Pruebas Organizacional** — Principios de pruebas a nivel organización (fuera del alcance de StrayMark) > - **Estrategia de Pruebas** — Estrategia de pruebas a nivel proyecto (puede referenciarse en gobernanza del proyecto) > - **Plan de Pruebas** — Este documento: planificación de pruebas específica para una funcionalidad, componente o cambio @@ -198,4 +198,4 @@ related: [] | Fecha | [YYYY-MM-DD] | | Comentarios | [Notas] | - + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-ADR.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-ADR.md new file mode 100644 index 0000000..30dc2c8 --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-ADR.md @@ -0,0 +1,148 @@ +--- +id: ADR-YYYY-MM-DD-NNN +title: [架构决策标题] +status: draft +created: YYYY-MM-DD +updated: YYYY-MM-DD +agent: [agent-name-v1.0] +confidence: high | medium | low +review_required: true + +# --- 审批工作流（可选，审批时填写）--- +# reviewed_by: <审批人标识> # 邮箱 | github 用户 | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: medium | high | critical +eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable +iso_42001_clause: [] # 4 | 5 | 6 | 7 | 8 | 9 | 10 +alternatives_documented: [] # 链接到相关的 AIDEC-* 文档 +api_changes: [] # 受此决策影响的 API 端点（例如 "POST /api/v2/users"） +tags: [] +related: [] +supersedes: [] +--- + +# ADR: [架构决策标题] + +## 状态 + +[draft | accepted | deprecated | superseded] + +**注意**：本文档由 AI 代理创建，需要人工审查。 + +> **不可变性规则**：ADR 一旦达到 `accepted` 状态，则不得修改。如果决策发生变更，请创建一份新的 ADR，并在其前置元数据中设置 `supersedes: ADR-YYYY-MM-DD-NNN`。原始 ADR 的状态将变更为 `superseded`。 + +## 背景 + +[描述技术和业务背景。哪些因素在起作用（技术、政策、社会、项目相关）。语言应保持中立，仅描述事实。] + +## 决策 + +[描述架构决策及其理由。使用主动语态："我们将使用……"、"我们将实现……"] + +## 考虑过的替代方案 + +### 1. [替代方案 1] +- **描述**: [内容是什么] +- **优点**: [优势] +- **缺点**: [劣势] +- **未采用原因**: [放弃的理由] + +### 2. [替代方案 2] +- **描述**: [内容是什么] +- **优点**: [优势] +- **缺点**: [劣势] +- **未采用原因**: [放弃的理由] + +## 后果 + +> 根据相关的 ISO/IEC 25010:2023 质量特性评估后果。 +> 完整质量模型请参阅 `00-governance/ISO-25010-2023-REFERENCE.md`。 + +### 正面影响 +- [收益 1] +- [收益 2] + +### 负面影响 +- [成本或权衡 1] +- [成本或权衡 2] + +### 中性影响 +- [既非明显正面也非负面的后果] + +### 质量影响评估 + +> 仅填写受此决策影响的质量特性。 + +| 质量特性 (ISO 25010:2023) | 影响 | 描述 | +|--------------------------|------|------| +| 功能适宜性 | [+/-/~] | [此决策如何影响功能覆盖、正确性或适当性] | +| 性能效率 | [+/-/~] | [对时间行为、资源利用或容量的影响] | +| 兼容性 | [+/-/~] | [对共存性或互操作性的影响] | +| 交互能力 | [+/-/~] | [对可学习性、可操作性、包容性等的影响] | +| 可靠性 | [+/-/~] | [对无故障性、可用性、容错性或可恢复性的影响] | +| 安全性 | [+/-/~] | [对机密性、完整性、真实性或抗攻击性的影响] | +| 可维护性 | [+/-/~] | [对模块化、可分析性、可修改性或可测试性的影响] | +| 灵活性 | [+/-/~] | [对适应性、可安装性或可扩展性的影响] | +| 安全防护 | [+/-/~] | [对操作约束、故障安全、危险警告或安全集成的影响] | + +> **图例**：`+` = 正面影响，`-` = 负面影响，`~` = 中性/权衡。删除不适用的行。 + +## 受影响的组件 + +| 组件 | 变更类型 | 影响程度 | +|------|---------|---------| +| [组件 1] | [新增/修改/移除] | [高/中/低] | +| [组件 2] | [新增/修改/移除] | [高/中/低] | + +## 实施计划 + +1. [步骤 1] +2. [步骤 2] +3. [步骤 3] + +## 成功指标 + +- [如何判断决策是否正确] +- [需要监控哪些指标] + +## 验证标准 + +> 定义可衡量的标准来评估此决策是否正确。 + +| 指标 | 目标值 | 测量方法 | 时间线 | +|------|-------|---------|--------| +| [例如：响应时间] | [例如：< 200ms] | [例如：p95 负载测试] | [例如：部署后 30 天] | +| [指标 2] | [目标值] | [方法] | [时间线] | + +## 架构图 + +> 当此决策涉及架构变更时，请包含适当层级的 C4 图。 +> 语法参考请参阅 `00-governance/C4-DIAGRAM-GUIDE.md`。 + +```mermaid +C4Context + title 系统上下文 — [决策标题] + + Person(user, "用户", "描述") + System(system, "系统", "描述") + + Rel(user, system, "使用") +``` + +> **指导**：系统级决策使用 `C4Context`，服务/容器级决策使用 `C4Container`，内部模块决策使用 `C4Component`。如不需要架构图，请删除本节。 + +## 参考资料 + +- [相关文档链接] +- [参考的论文、文章或资源] + +--- + +## 修订历史 + +| 日期 | 作者 | 变更内容 | +|------|------|---------| +| YYYY-MM-DD | [agent/human] | 初始创建 | + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-AIDEC.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-AIDEC.md new file mode 100644 index 0000000..262f9bf --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-AIDEC.md @@ -0,0 +1,92 @@ +--- +id: AIDEC-YYYY-MM-DD-NNN +title: [决策标题] +status: accepted +created: YYYY-MM-DD +agent: [agent-name-v1.0] +confidence: high | medium | low +review_required: false + +# --- 审批工作流（可选，审批时填写）--- +# reviewed_by: <审批人标识> # 邮箱 | github 用户 | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: low | medium | high | critical +eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable +nist_genai_risks: [] # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain +iso_42001_clause: [] # 4 | 5 | 6 | 7 | 8 | 9 | 10 +tags: [] +related: [] +--- + +# AIDEC: [决策标题] + +## 背景 + +[描述需要做出决策的情境] + +## 问题 + +[清晰定义需要解决的问题] + +## 考虑过的替代方案 + +### 替代方案 1: [名称] + +**描述**: [该替代方案的具体内容] + +**优点**: +- [优势 1] +- [优势 2] + +**缺点**: +- [劣势 1] +- [劣势 2] + +### 替代方案 2: [名称] + +**描述**: [该替代方案的具体内容] + +**优点**: +- [优势 1] +- [优势 2] + +**缺点**: +- [劣势 1] +- [劣势 2] + +### 替代方案 3: [名称]（如适用） + +... + +## 决策 + +**选定方案**: 替代方案 [N] - [名称] + +**理由**: [为什么选择该方案而非其他方案] + +## 后果 + +### 正面影响 +- [正面后果 1] +- [正面后果 2] + +### 负面影响 +- [负面后果或权衡 1] +- [负面后果或权衡 2] + +### 风险 +- [已识别的风险及适用的缓解措施] + +## 实施 + +[简要描述如何实施该决策] + +## 参考资料 + +- [相关链接或参考] +- [参考的文档] + +--- + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-AILABEL.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-AILABEL.md new file mode 100644 index 0000000..bdffe1e --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-AILABEL.md @@ -0,0 +1,118 @@ +--- +id: AILABEL-YYYY-MM-DD-NNN +title: "[服务] GB 45438 内容标识方案" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: medium +review_required: true + +# --- 审批工作流（可选，审批时填写）--- +# reviewed_by: <审批人标识> # 邮箱 | github 用户 | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: medium +gb45438_applicable: true +gb45438_content_types: [] # text | image | audio | video | virtual_scene 的子集 +gb45438_explicit_label_strategy: null # disclaimer | watermark | caption | audio_cue | banner +gb45438_implicit_metadata_format: null # C2PA | XMP | EXIF | custom | none +gb45438_distributor_obligations_documented: false +iso_42001_clause: [8] +tags: [china, gb45438, labeling, ai-generated-content] +related: [] +--- + +# AILABEL: [服务] GB 45438 内容标识方案 + +> **重要提示**:此文档为 AI 代理创建的草稿,部署前需经人工审核与批准。 +> +> 与 **GB 45438-2025** 《网络安全技术 人工智能生成合成内容标识方法》(自 2025-09-01 起施行)及国家网信办《人工智能生成合成内容标识办法》一致。在范围内的服务必须同时实施 **显式**(可视)和 **隐式**(机器可读)标识。 + +## 1. 内容类型覆盖 + +| 内容类型 | 是否在范围 | 生成方式 | 体量 | +|---------|----------|--------|------| +| 文本 | [是/否] | [LLM 续写 / 对话 / 摘要 / 翻译] | [tokens/天] | +| 图像 | [是/否] | [文生图 / 图像编辑 / 换脸 / 姿势编辑] | [图像/天] | +| 音频 | [是/否] | [声音克隆 / TTS / 音乐生成] | [分钟/天] | +| 视频 | [是/否] | [文生视频 / 图生视频 / 换脸 / 姿势] | [分钟/天] | +| 虚拟场景 | [是/否] | [沉浸式 / 高拟真环境] | [场景/天] | + +## 2. 显式标识(可视指示) + +> 显式标识必须可被普通用户感知。形式取决于媒介。 + +| 内容类型 | 策略 | 位置 | 文案 / 视觉 | +|---------|------|------|-----------| +| 文本 | [免责声明 / banner / 行内标签] | [对话头部 / 消息脚注] | [例如:"本内容由人工智能生成"] | +| 图像 | [水印 / 字幕 / 角标] | [右下角 / 居中覆盖] | [Logo + 文字 + 不透明度] | +| 音频 | [音频提示 / 口语披露] | [片段开始 / 每 N 秒] | [例如:1秒提示音 + 口语 "AI 生成"] | +| 视频 | [水印 + 字幕] | [持续角标 + 起始帧] | [规格] | +| 虚拟场景 | [持续 banner / 进入前提示] | [HUD / 加载界面] | [规格] | + +## 3. 隐式标识(机器可读元数据) + +> 根据 GB 45438 第5节,隐式标识在文件头嵌入元数据或数字水印。 **必填字段**:**内容类型**、**服务提供者名称或代码**、**内容标识号**。 + +### 3.1 元数据格式 + +- **选定格式**:[C2PA / XMP / EXIF / custom / none] +- **选择理由**:[兼容性、持久性、生态支持] + +### 3.2 必填字段(每件生成内容必须填充) + +| 字段 | 来源 / 生成器 | 示例 | +|------|------------|------| +| `content_type` | 模态分发器 | `text` / `image` / `audio` / `video` / `virtual_scene` | +| `service_provider_code` | 内部配置 | [备案成功后由 CAC 发放 — 见 CACFILE-...] | +| `content_id` | UUIDv7 / ULID | [每件唯一,可在日志中追溯] | +| `created_at` | 服务器时间(UTC+8) | [ISO-8601] | +| `model_reference` | MCARD 链接 | [MCARD-YYYY-MM-DD-NNN] | + +### 3.3 数字水印(鼓励) + +- [ ] 嵌入可见水印 +- [ ] 嵌入不可见水印 — 算法:[DWT-DCT / SS / LSB / 自有] +- **持久性**:[抵抗 JPEG 重压缩 / 视频重编码 / 裁剪] + +## 4. 在导出 / 下载后的持久性 + +| 操作 | 显式标识保留 | 隐式元数据保留 | 备注 | +|------|----------|--------------|------| +| 直接下载 | [是/否] | [是/否] | [格式相关] | +| 由其他工具重新导出 | [是/否] | [是/否] | [元数据被剥离的风险] | +| 截图 / 屏幕录制 | [是/否] | [是/否] | [仅水印兜底] | +| 重编码 | [是/否] | [是/否] | [需鲁棒水印] | + +## 5. 分发者验证钩子 + +> 分发者与平台必须在元数据存在时进行验证,识别合成内容时显著呈现提示。 + +- **暴露的验证 API**:[URL 或不适用] +- **下游平台的检测信号**:[如何在不共享模型的情况下确认来源] +- **禁止移除合成内容标签**:[执行机制] +- **验证成功时的用户提示**:[UX 模式] + +## 6. 测试方案 + +| 测试 | 通过标准 | 状态 | +|------|--------|------| +| 全部 5 种内容类型显式标识可见 | [人工审核] | [待执行] | +| 抽样输出 100% 包含隐式元数据 | [N 个样本的自动扫描] | [待执行] | +| 下载 → 重新上传后标识保留 | [元数据无丢失] | [待执行] | +| 30% JPEG 重压缩后水印可检测 | [水印检测准确率 ≥ X%] | [待执行] | + +## 7. 关联资料 + +- **MCARD**:[`gb45438_applicable: true` 的模型卡] +- **CACFILE**:[算法备案 — 提供 `service_provider_code`] +- **TC260RA**:[标识失败风险分级] +- **ETH**:[伦理审查 — 透明度考量] + +## 批准 + +| 批准人 | 日期 | 决定 | 条件 | +|--------|------|------|------| +| [审核人] | [YYYY-MM-DD] | [批准 / 有条件批准 / 拒绝] | [条件(如有)] | + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-AILOG.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-AILOG.md new file mode 100644 index 0000000..5133d6d --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-AILOG.md @@ -0,0 +1,117 @@ +--- +id: AILOG-YYYY-MM-DD-NNN +title: [操作的描述性标题] +status: accepted +created: YYYY-MM-DD +agent: [agent-name-v1.0] +confidence: high | medium | low +review_required: false +risk_level: low | medium | high | critical +eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable +nist_genai_risks: [] # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain +iso_42001_clause: [] # 4 | 5 | 6 | 7 | 8 | 9 | 10 +lines_changed: 0 # 可自动计算 +files_modified: [] # 可自动计算 +observability_scope: none # none | basic | full — 当 OTel 监测相关时设置 +tags: [] +related: [] +--- + +# AILOG: [标题] + +## 摘要 + +[简要描述执行了什么操作及其原因] + +## 背景 + +[促使执行此操作的情境] + +## 执行的操作 + +1. [操作 1] +2. [操作 2] +3. [操作 3] + +## 批次台账 (Batch Ledger) + +> 对跨越 3+ 批次或 >1 天执行的 Charter 使用此章节。 +> 每个批次的 commit 落地**立即**更新对应条目，使用 +> `straymark charter batch-complete `。Charter 关闭时 +> 仍为 `(pending)` 的条目会导致 `straymark charter drift` 失败。 +> +> 对于单批次或单会话的 AILOG，请完全省略此章节——上方的 +> `## 执行的操作` 已足够。 + +### Batch 1 — [来自 Charter §Tasks 的名称] + +(pending) + +### Batch 2 — [来自 Charter §Tasks 的名称] + +(pending) + +## 修改的文件 + +| 文件 | 变更行数 (+/-) | 变更描述 | +|------|---------------|----------| +| `path/to/file.ts` | +N/-M | [变更描述] | + +## 所做的决策 + +[如有相关决策，请简要记录或引用 AIDEC] + +## 影响 + +- **功能性**: [描述] +- **性能**: [描述或不适用] +- **安全性**: [描述或不适用] +- **隐私**: [描述或不适用] +- **环境影响**: [描述或不适用] + +## 验证 + +- [ ] 代码编译无错误 +- [ ] 测试通过 +- [ ] 已执行人工审查 +- [ ] 安全扫描已通过（如 risk_level 为 high/critical） +- [ ] 隐私审查已完成（如涉及个人身份信息） + +## EU AI Act 相关考量 + +> 仅当 `eu_ai_act_risk` 为 `high` 或 `limited` 时填写本节。 + +- **风险分类**: [high | limited] +- **附录 III 类别**: [如适用 — 指定类别] +- **是否需要合规评估**: [是/否] +- **透明度义务**: [适用义务的描述] + +## NIST GenAI 风险评估 + +> 当变更涉及生成式 AI 组件时填写本节。 +> 参考：NIST AI 600-1（生成式 AI 概况）。 + +| # | 类别 | 是否适用 | 描述 | 缓解措施 | +|---|------|---------|------|----------| +| 1 | CBRN 信息 | [是/否] | | | +| 2 | 虚构内容 | [是/否] | | | +| 3 | 危险/暴力/仇恨内容 | [是/否] | | | +| 4 | 数据隐私 | [是/否] | | | +| 5 | 环境影响 | [是/否] | | | +| 6 | 有害偏见/同质化 | [是/否] | | | +| 7 | 人机配置 | [是/否] | | | +| 8 | 信息完整性 | [是/否] | | | +| 9 | 信息安全 | [是/否] | | | +| 10 | 知识产权 | [是/否] | | | +| 11 | 淫秽/辱骂内容 | [是/否] | | | +| 12 | 价值链/组件集成 | [是/否] | | | + +## 补充说明 + +[任何其他相关信息] + +> **可观测性说明**：如果此变更修改了可观测性监测（新增 span、变更属性、管道配置），请描述可观测性影响并添加标签 `observabilidad`。 + +--- + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-CACFILE.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-CACFILE.md new file mode 100644 index 0000000..10a6740 --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-CACFILE.md @@ -0,0 +1,121 @@ +--- +id: CACFILE-YYYY-MM-DD-NNN +title: "[服务名称] 网信办算法备案" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: medium +review_required: true + +# --- 审批工作流（可选，审批时填写）--- +# reviewed_by: <审批人标识> # 邮箱 | github 用户 | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: high +cac_filing_required: true +cac_filing_type: algorithm # algorithm | generative_ai | dual +cac_filing_status: pending # pending | provincial_submitted | provincial_approved | national_submitted | national_approved | rejected | not_required +cac_filing_number: null # 备案成功后填入,例如:"网信算备XXXXXXXXXXXX" +cac_provincial_authority: null # 受理本次备案的省级网信办 +cac_national_decision_date: null # 国家网信办公布决定日期 YYYY-MM-DD +iso_42001_clause: [8] +tags: [china, cac, algorithm-filing] +related: [] +--- + +# CACFILE: [服务名称] 网信办算法备案 + +> **重要提示**:此文档为 AI 代理创建的草稿。在向国家互联网信息办公室任何提交之前,需经法务与合规负责人审核。 +> +> 根据《互联网信息服务算法推荐管理规定》和《生成式人工智能服务管理暂行办法》,具有 **舆论属性或社会动员能力** 的对外服务须办理算法备案。生成式 AI 大模型还需 **双重备案**:省级安全评估 + 国家级算法备案。 + +## 服务概述 + +- **服务名称**:[面向用户的名称] +- **提供者法律实体**:[在中国大陆注册的公司/分支] +- **服务形式**:[互联网信息服务 / APP / 小程序 / API / 其他] +- **应用领域**:[内容推荐 / 搜索排序 / 个性化 / 生成式 AI / 合成 / 其他] +- **算法类型**:[生成合成 / 个性化推送 / 排序精选 / 检索过滤 / 调度决策] +- **目标受众**:[公众 / 特定行业 / 未成年人 / 其他] +- **适用场景**:[具体使用场景] + +## 舆论属性 / 社会动员能力评估 + +需要备案的服务通常具备以下属性。请记录评估: + +- [ ] 生成 / 合成 / 传播可被公众查看的内容 +- [ ] 通过排序、推荐或内容选择影响用户观点 +- [ ] 具备动员用户进行集体行动的能力 +- [ ] 在新闻、社交媒体、音视频或直播领域运营 + +**结论**:[需要备案 / 不需要备案] — [理由] + +## 训练数据描述 + +- **数据来源**:[公开语料 / 自有 / 第三方授权 / 用户生成] +- **数据规模**:[token / 图像 / 样本数量近似值] +- **地理来源**:[境内 / 境外 / 混合 — 注意《个人信息保护法》跨境影响] +- **来源合法性**:[根据《生成式人工智能服务管理暂行办法》第7条:合法、准确、客观、多样性] +- **训练数据中的个人信息**:[是/否 — 如是,关联 PIPIA-XXXX] +- **过滤的敏感类别**:[根据《个人信息保护法》第28条移除敏感数据的方法] + +## 关键词阻断策略 + +> 根据暂行办法,服务提供者须防止生成颠覆国家政权、煽动分裂、破坏国家统一、宣扬恐怖主义/极端主义、宣扬民族仇恨/民族歧视、暴力、淫秽色情等内容。 + +- **关键词列表来源**:[内部列表参考、版本、最近更新] +- **更新周期**:[列表复审频率] +- **分层控制**:[输入预过滤 / 生成后过滤 / 拒绝响应 / 安全补全] +- **审计样本**:[备案保留的代表性样本路径] + +## 测试题集 + +- **测试集规模**:[红队提示词数量] +- **覆盖范围**:[测试类别:政治敏感、暴力、自残、仇恨、歧视、隐私、未成年人等] +- **通过阈值**:[要求的通过率] +- **最近测试结果**:[日期 / 通过率 / 文档参考] + +## 内部算法管理制度 + +- **指定责任人**:[姓名 / 角色,具备完整中文资质] +- **内部审查流程**:[部署前审查步骤] +- **投诉处理**:[用户投诉渠道 + SLA] +- **日志与可追溯性**:[模型输入 / 输出如何留存以确保问责] + +## 算法安全责任报告 + +根据《互联网信息服务算法推荐管理规定》第24条,准备《算法安全责任落实情况报告》。概述: + +- **算法机制说明**:[算法运行机制的通俗描述] +- **用户告知**:[如何告知用户算法决策] +- **退出机制**:[用户如何关闭个性化] +- **人工干预能力**:[运营者如何覆盖算法输出] + +## 自评估 + +| 风险领域 | 发现 | 严重程度 | 缓解措施 | +|---------|------|--------|--------| +| 内容合规(违法内容生成) | [发现] | [低/中/高] | [措施] | +| 个人信息保护 | [发现] | [低/中/高] | [措施] | +| 偏见 / 不合理差别待遇 | [发现] | [低/中/高] | [措施] | +| 知识产权 | [发现] | [低/中/高] | [措施] | +| 未成年人保护 | [发现] | [低/中/高] | [措施] | + +## 备案轨迹 + +| 阶段 | 日期 | 结果 / 备案号 | +|------|------|--------------| +| 内部签核 | [YYYY-MM-DD] | [文档参考] | +| 省级提交 | [YYYY-MM-DD] | [受理回执号] | +| 省级决定 | [YYYY-MM-DD] | [批准 / 拒绝 — 理由] | +| 国家级提交 | [YYYY-MM-DD] | [受理回执号] | +| 国家级决定 | [YYYY-MM-DD] | [发放的备案号] | +| 公开披露 | [YYYY-MM-DD] | [向终端用户展示备案号的 URL] | + +## 批准 + +| 批准人 | 日期 | 决定 | 条件 | +|--------|------|------|------| +| [合规负责人] | [YYYY-MM-DD] | [批准 / 有条件批准 / 拒绝] | [条件(如有)] | + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-DPIA.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-DPIA.md new file mode 100644 index 0000000..3b2294d --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-DPIA.md @@ -0,0 +1,97 @@ +--- +id: DPIA-YYYY-MM-DD-NNN +title: "[系统/流程] 数据保护影响评估" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: low # DPIA 需要大量人工判断 +review_required: true # 始终为必须 + +# --- 审批工作流（可选，审批时填写）--- +# reviewed_by: <审批人标识> # 邮箱 | github 用户 | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: high +eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable +gdpr_article_35: true # GDPR 第 35 条触发 DPIA +iso_42001_clause: [6, 8] +dpo_consulted: false +supervisory_authority_consulted: false +tags: [privacy, gdpr, dpia] +related: [] +--- + +# DPIA: [系统/流程] 数据保护影响评估 + +> **重要提示**：本文档是由 AI 代理创建的草稿。 +> 在继续之前，需要经过人工审查和批准。 + +## 处理活动描述 + +- **处理性质**: [描述数据如何被收集、存储、使用和删除] +- **范围**: [处理规模 — 数据主体数量、数据量、地理范围] +- **背景**: [控制者与数据主体之间的关系、期望] +- **目的**: [处理活动的具体目的] +- **法律依据 (GDPR 第 6 条)**: [consent / contract / legal_obligation / vital_interests / public_task / legitimate_interests] +- **数据主体类别**: [员工、客户、未成年人、患者等] +- **个人数据类别**: [姓名、电子邮件、健康数据、生物特征数据、位置信息等] +- **接收方**: [谁接收或有权访问数据] +- **国际传输**: [国家/地区、传输机制（SCCs、充分性决定、BCRs）] +- **保留期限**: [数据保留时间及确定保留期限的标准] + +## 必要性与比例性 + +- **必要性评估**: [为什么此处理对于实现既定目的是必要的] +- **目的限制**: [处理如何限定在既定目的范围内] +- **数据最小化**: [如何仅收集和处理最少量的必要数据] +- **存储限制**: [数据保留如何限定在必要范围内] +- **数据质量**: [如何确保数据的准确性和完整性] + +## 风险评估 + +### 数据主体面临的风险 + +| 风险 | 可能性 | 严重性 | 风险等级 | 风险来源 | 影响性质 | +|------|--------|--------|---------|---------|---------| +| [风险 1] | [低/中/高] | [低/中/高] | [低/中/高] | [来源] | [身体/物质/非物质] | + +### 权利和自由面临的风险 + +| 风险 | 可能性 | 严重性 | 风险等级 | 风险来源 | 影响性质 | +|------|--------|--------|---------|---------|---------| +| [风险 1] | [低/中/高] | [低/中/高] | [低/中/高] | [来源] | [身体/物质/非物质] | + +## 风险缓解措施 + +| 风险 | 措施 | 类型 | 残余风险 | 责任人 | +|------|------|------|---------|--------| +| [风险 1] | [缓解措施] | [技术/组织/法律] | [低/中/高] | [角色/人员] | + +## 咨询 + +> 如果缓解后残余风险仍然较高，根据 GDPR 第 36 条，必须咨询监管机构。 + +- **数据保护官意见**: [DPO 意见和建议] +- **是否咨询数据主体**: [是/否] — [方法：调查问卷、焦点小组、公众咨询等] +- **是否咨询监管机构**: [是/否] — [参考编号或详细信息（如适用）] + +## AI 相关特别考量 + +> 当处理涉及 AI 系统时（尤其是在 EU AI Act 框架下）填写本节。 + +- **自动化决策 (GDPR 第 22 条)**: [处理是否涉及对数据主体产生法律或重大影响的完全自动化决策？描述保障措施] +- **解释权**: [数据主体如何获取关于所涉逻辑的有意义信息] +- **人工监督措施**: [描述人在环路中（human-in-the-loop）或人在环路上（human-on-the-loop）机制] +- **对数据主体的透明度**: [如何告知数据主体 AI 参与处理其数据] + +## 审查计划 + +- **下次审查日期**: [YYYY-MM-DD] +- **审查触发事件**: + - [处理范围或目的发生变更] + - [新增个人数据类别] + - [法规变更] + - [安全事件] +- **审查负责人**: [负责执行审查的角色/人员] + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-ETH.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-ETH.md new file mode 100644 index 0000000..7af1d1a --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-ETH.md @@ -0,0 +1,204 @@ +--- +id: ETH-YYYY-MM-DD-NNN +title: [伦理审查标题] +status: draft +created: YYYY-MM-DD +agent: [agent-name-v1.0] +confidence: medium | low +review_required: true + +# --- 审批工作流（可选，审批时填写）--- +# reviewed_by: <审批人标识> # 邮箱 | github 用户 | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: high | critical +eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable +nist_genai_risks: [] # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain +iso_42001_clause: [] # 4 | 5 | 6 | 7 | 8 | 9 | 10 +gdpr_legal_basis: none # consent | contract | legal_obligation | vital_interests | public_task | legitimate_interests | none +fria_required: false # Fundamental Rights Impact Assessment +tags: [] +related: [] +approved_by: null +approved_date: null +--- + +# ETH: [伦理审查标题] + +> **重要提示**：本文档是由 AI 智能体创建的草稿。 +> 在继续之前，需要经过人工审查和批准。 + +## 摘要 + +[简要描述需要考虑的伦理问题] + +## 背景 + +[描述产生伦理考量的具体情况] + +## EU AI Act 风险分类 + +> 参考：EU AI Act, Annex III。 + +| 风险等级 | 义务要求 | 是否适用 | +|----------|----------|----------| +| **不可接受** | 禁止部署该系统 | [ ] | +| **高风险** | 需全面合规——合规评估、CE 标志、注册、上市后监控 | [ ] | +| **有限风险** | 透明度义务——必须告知用户正在与 AI 交互 | [ ] | +| **最低风险** | 无特定义务——鼓励遵循自愿行为准则 | [ ] | + +- **Annex III 类别**（如属高风险）：[指定：生物识别、关键基础设施、教育、就业、基本服务、执法、移民、司法、民主进程] +- **义务清单**（如属高风险）： + - [ ] 已建立风险管理体系 (Art. 9) + - [ ] 已满足数据治理要求 (Art. 10) + - [ ] 已准备技术文档 (Art. 11, Annex IV) + - [ ] 已启用记录保存 (Art. 12) + - [ ] 已提供透明度信息 (Art. 13) + - [ ] 已落实人工监督措施 (Art. 14) + - [ ] 已确保准确性、鲁棒性和网络安全 (Art. 15) + +## 关注领域 + +### 1. 数据隐私 + +- **涉及数据**：[处理了哪些数据] +- **敏感程度**：[个人身份信息、健康数据、财务数据等] +- **管辖范围**：[GDPR、CCPA 等] +- **关注事项**：[列出具体关注点] + +#### GDPR 法律依据 + +> 依据 GDPR Art. 6。处理个人数据时填写。 + +| 处理活动 | 法律依据 (Art. 6) | 理由说明 | 数据保留期限 | +|----------|-------------------|----------|-------------| +| [活动] | [consent/contract/legal_obligation/vital_interests/public_task/legitimate_interests] | [为何适用此依据] | [期限] | + +#### 数据保护影响评估参考 + +- **是否存在 DPIA**：[是/否] +- **DPIA 文档**：[DPIA-YYYY-MM-DD-NNN（如适用）] + +### 2. 偏见与公平性 + +- **受影响群体**：[可能受到影响的人群] +- **偏见风险**：[已识别的潜在偏见] +- **建议缓解措施**：[如何应对这些问题] + +#### 受保护特征 + +| 特征 | 是否可能受影响 | 评估 | 缓解措施 | +|------|--------------|------|----------| +| 年龄 | [是/否] | [评估] | [缓解措施] | +| 残障 | [是/否] | [评估] | [缓解措施] | +| 性别 | [是/否] | [评估] | [缓解措施] | +| 种族/民族 | [是/否] | [评估] | [缓解措施] | +| 宗教/信仰 | [是/否] | [评估] | [缓解措施] | +| 性取向 | [是/否] | [评估] | [缓解措施] | +| 社会经济地位 | [是/否] | [评估] | [缓解措施] | +| 其他 | [是/否] | [评估] | [缓解措施] | + +### 3. 透明度 + +- **用户沟通**：[向用户传达了哪些信息] +- **知情同意**：[如何获取同意] +- **解释权**：[如何保障解释权] + +### 4. 安全性 + +- **已识别风险**：[列出风险] +- **潜在影响**：[发生安全事故的后果] +- **建议控制措施**：[安全措施] + +### 5. 社会影响 + +- **收益**：[对谁有益、如何受益] +- **潜在危害**：[对谁有害、如何受害] +- **权衡分析**：[成本效益分析] + +## 环境影响 + +> 当系统涉及 AI 模型训练或大量计算资源时填写。 + +| 指标 | 数值 | 备注 | +|------|------|------| +| 训练能耗估算 (kWh) | [数值] | [计算方法] | +| 二氧化碳当量（吨） | [数值] | [使用的电网碳排放强度] | +| 使用硬件 | [GPU/TPU 型号及数量] | [云服务商/区域] | +| 每次推理成本 | [数值] | [平均/峰值] | +| 缓解措施 | [描述] | [碳抵消、高效架构等] | + +## 双重用途潜力 + +> 评估系统是否可能被挪用于有害用途。 + +- **有益用途**： + - [预期有益用途 1] + - [预期有益用途 2] +- **潜在滥用**： + - [潜在滥用 1] + - [潜在滥用 2] +- **已实施的安全保障**： + - [保障措施 1] + - [保障措施 2] +- **残余风险评估**：[低/中/高——描述实施保障措施后的剩余风险] + +## 基本权利影响评估 (FRIA) + +> EU AI Act Art. 27 要求高风险 AI 系统的部署者完成此评估。 +> 仅当 `eu_ai_act_risk` 为 `high` 且系统正在部署时填写本节。 + +- **受影响人群类别**：[AI 系统使用所影响的人群] +- **基本权利的具体风险**：[识别对尊严、非歧视、隐私、数据保护、言论自由等的风险] +- **使用期限和频率**：[系统将被使用的频率和时长] +- **治理措施**：[确保基本权利的组织措施] +- **人工监督流程**：[如何按 Art. 14 实施人工监督] + +## 智能体建议 + +1. [建议 1] +2. [建议 2] +3. [建议 3] + +## 留待人工审查员的问题 + +1. [智能体无法解决的问题] +2. [需要人工判断的决策] +3. [需要验证的方面] + +## 审查清单 + +### 人工审查员须知 + +- [ ] 我已阅读并理解所提出的关注事项 +- [ ] 我已评估隐私风险 +- [ ] 我已考虑对弱势群体的影响 +- [ ] 我已核实法规合规性 +- [ ] 我已评估建议的缓解措施 +- [ ] 我已审查 EU AI Act 风险分类（如适用） +- [ ] 我已审查 FRIA（如属高风险部署） +- [ ] 我已审查环境影响评估（如适用） + +### 决定 + +- [ ] **批准** — 按建议方案执行 +- [ ] **有条件批准** — 修改后执行 +- [ ] **驳回** — 不予执行 +- [ ] **需要进一步分析** — 升级处理或深入调查 + +## 审查员备注 + +[供人工审查员记录其分析和决定的空间] + +--- + +## 审批 + +| 字段 | 值 | +|------|-----| +| 审批人 | [姓名] | +| 日期 | [YYYY-MM-DD] | +| 决定 | [APPROVED/REJECTED/CONDITIONAL] | +| 条件 | [如适用] | + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-INC.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-INC.md new file mode 100644 index 0000000..68ebd06 --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-INC.md @@ -0,0 +1,154 @@ +--- +id: INC-YYYY-MM-DD-NNN +title: [事件标题] +status: draft +created: YYYY-MM-DD +agent: [agent-name-v1.0] +confidence: medium +review_required: true + +# --- 审批工作流（可选，审批时填写）--- +# reviewed_by: <审批人标识> # 邮箱 | github 用户 | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: high | critical +severity: SEV1 | SEV2 | SEV3 | SEV4 +eu_ai_act_applicable: false +incident_report_deadline: null # YYYY-MM-DD — regulatory deadline if applicable +iso_42001_clause: [] # 4 | 5 | 6 | 7 | 8 | 9 | 10 +observability_scope: none # none | basic | full — set when OTel instrumentation is relevant +tags: [] +related: [] +incident_date: YYYY-MM-DD +resolved_date: null +--- + +# INC: [事件标题] + +> **部分分析**：本文档包含 AI 智能体的分析内容。 +> 最终结论和纠正措施需要人工审查。 + +## 事件概要 + +| 字段 | 值 | +|------|-----| +| 严重程度 | [SEV1/SEV2/SEV3/SEV4] | +| 开始日期/时间 | [YYYY-MM-DD HH:MM UTC] | +| 解决日期/时间 | [YYYY-MM-DD HH:MM UTC] | +| 持续时长 | [X 小时 Y 分钟] | +| 受影响服务 | [服务列表] | +| 受影响用户 | [估算数量] | +| 业务影响 | [描述] | + +## 严重程度定义 + +| 严重程度 | 定义 | +|----------|------| +| SEV1 | 服务完全中断，业务受到严重影响 | +| SEV2 | 严重降级，主要功能受到影响 | +| SEV3 | 部分降级，存在替代方案 | +| SEV4 | 影响较小，仅少数用户受到影响 | + +## 时间线 + +> 如果系统使用 OpenTelemetry，请包含 trace-id 作为关联证据。 + +| 时间 (UTC) | 事件 | Trace ID | Span ID | 仪表盘链接 | +|------------|------|----------|---------|-----------| +| HH:MM | [首次检测到症状] | [trace-id（如有）] | [span-id] | [链接] | +| HH:MM | [触发告警] | | | | +| HH:MM | [通知团队] | | | | +| HH:MM | [初步诊断] | | | | +| HH:MM | [实施缓解措施] | | | | +| HH:MM | [服务恢复] | | | | +| HH:MM | [事件关闭] | | | | + +## 根因分析 + +### 直接原因 +[直接导致故障的原因] + +### 间接原因 +1. [间接因素 1] +2. [间接因素 2] + +### 根本原因（智能体分析） +[智能体对根本原因的分析] + +> **注意**：此分析需要技术团队的验证。 + +## 影响 + +### 技术影响 +- [技术影响 1] +- [技术影响 2] + +### 业务影响 +- [业务影响 1] +- [业务影响 2] + +### 用户影响 +- [用户影响 1] +- [用户影响 2] + +## 已采取的缓解措施 + +1. [为解决事件所采取的措施] +2. [为解决事件所采取的措施] + +## 建议纠正措施 + +> 这些建议需要人工审查和优先级排序。 + +| # | 措施 | 类型 | 优先级 | 负责人 | 截止日期 | +|---|------|------|--------|--------|----------| +| 1 | [措施] | 预防 | [High/Medium/Low] | [待定] | [待定] | +| 2 | [措施] | 检测 | [High/Medium/Low] | [待定] | [待定] | +| 3 | [措施] | 响应 | [High/Medium/Low] | [待定] | [待定] | + +## 经验教训 + +### 做得好的方面 +- [积极方面 1] +- [积极方面 2] + +### 需要改进的方面 +- [待改进方面 1] +- [待改进方面 2] + +### 侥幸之处 +- [本可能更严重的方面] + +## EU AI Act 事件报告 + +> 对于 EU AI Act 下的高风险 AI 系统，事件必须在以下时限内向市场监管机构报告： +> - **15 天**（标准事件） +> - **10 天**（导致死亡的事件） +> - **2 天**（大范围或非常严重的事件） +> +> 参考：Article 73, EU AI Act。 +> +> 仅当 `eu_ai_act_applicable` 为 `true` 时填写本节。 + +| 字段 | 值 | +|------|-----| +| 报告截止日期 | [YYYY-MM-DD] | +| 是否已通知主管机构 | [是/否/不适用] | +| 报告编号 | [已提交的参考编号] | + +## 待解决问题 + +1. [需要进一步调查的问题] +2. [需要团队讨论的问题] + +--- + +## 事后复盘 + +| 字段 | 值 | +|------|-----| +| 审查人 | [姓名] | +| 审查日期 | [YYYY-MM-DD] | +| 状态 | [Draft/Reviewed/Closed] | + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-MCARD.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-MCARD.md new file mode 100644 index 0000000..0ae8c83 --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-MCARD.md @@ -0,0 +1,158 @@ +--- +id: MCARD-YYYY-MM-DD-NNN +title: "[模型名称] Card" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: medium +review_required: true + +# --- 审批工作流（可选，审批时填写）--- +# reviewed_by: <审批人标识> # 邮箱 | github 用户 | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: medium +eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable +nist_genai_risks: [] # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain +iso_42001_clause: [8] +model_name: "" +model_type: LLM # LLM | classifier | regressor | generator | recommender | other +model_version: "" +provider: "" +license: "" +tags: [ai-model] +related: [] +--- + +# MCARD: [模型名称] Card + +> **重要提示**：本文档是由 AI 智能体创建的草稿。 +> 在继续之前，需要经过人工审查和批准。 + +## 模型详情 + +> 基于 Mitchell et al. (2019) -- "Model Cards for Model Reporting"。 + +| 字段 | 值 | +|------|-----| +| 开发者 | [开发该模型的组织或个人] | +| 模型日期 | [YYYY-MM-DD -- 模型训练或发布日期] | +| 模型版本 | [版本标识符] | +| 模型类型 | [LLM / classifier / regressor / generator / recommender / other] | +| 训练算法 | [用于训练的算法] | +| 基础模型 | [基础模型名称和版本（如为微调）；否则填 N/A] | +| 论文/资源 | [论文、博客文章或文档的 URL 或引用] | +| 引用格式 | [BibTeX 或纯文本引用] | +| 许可证 | [模型许可证 -- 例如 Apache 2.0、MIT、专有许可] | + +## 预期用途 + +### 主要预期用途 + +- [主要用例 1] +- [主要用例 2] + +### 主要预期用户 + +- [用户群体 1] +- [用户群体 2] + +### 超出范围的用途 + +- [模型不适用的用例 1] +- [模型不适用的用例 2] + +## 训练数据 + +> 为实现 SBOM 互操作性，建议与 CycloneDX `modelCard.modelParameters` 字段保持一致。 + +| 字段 | 值 | +|------|-----| +| 数据集名称 | [训练数据集名称] | +| 来源 | [数据获取来源] | +| 规模 | [样本数量、token 数量或存储大小] | +| 收集方法 | [数据收集方式] | +| 预处理 | [已应用的清洗、过滤、增强步骤] | +| 已知局限性 | [数据中的偏见、缺失或质量问题] | +| PII 评估 | [是否包含 PII 及其处理方式] | +| 许可证 | [训练数据适用的许可证] | + +## 性能指标 + +| 指标 | 数值 | 测试数据集 | 置信区间 | 条件 | +|------|:----:|-----------|:--------:|------| +| [Accuracy / F1 / BLEU 等] | [数值] | [数据集名称和划分] | [95% CI 范围] | [条件或配置] | + +### 分组评估 + +> 在适用时按相关子群体分别报告性能。 + +| 子群体 | 指标 | 数值 | 与整体基线比较 | +|--------|------|:----:|:-------------:| +| [子群体 1] | [指标] | [数值] | [+/- 相对于整体] | + +## 偏见与公平性评估 + +| 人群分组 | 指标 | 性能 | 与基线差异 | 已应用的缓解措施 | +|----------|------|:----:|:---------:|-----------------| +| [分组 1 -- 例如年龄段、性别、种族] | [指标] | [数值] | [+/- 百分比或绝对值] | [缓解措施描述] | + +## 环境影响 + +| 指标 | 数值 | 备注 | +|------|------|------| +| 训练能耗 (kWh) | [数值] | [计算方法或估算来源] | +| 二氧化碳当量（吨） | [数值] | [使用的电网碳排放强度] | +| 使用硬件 | [GPU/TPU 型号及数量] | [云服务商/区域] | +| 训练时长 | [小时/天] | [总计算时间] | +| 推理成本 | [每次请求或每千 token 成本] | [平均/峰值] | +| 区域/电网碳排放强度 | [区域名称] | [gCO2/kWh] | + +## 安全性考量 + +| 关注点 | 评估 | 详情 | +|--------|:----:|------| +| 已知漏洞 | [无/描述] | [CVE 引用或已知问题描述] | +| 对抗鲁棒性 | [Low / Medium / High] | [评估方法和结果] | +| 提示注入风险 | [Low / Medium / High] | [对提示注入的敏感性评估] | +| 数据投毒风险 | [Low / Medium / High] | [训练数据完整性评估] | +| 模型提取风险 | [Low / Medium / High] | [模型权重或行为被提取的风险] | + +## 伦理考量 + +- **是否使用敏感数据**：[训练中是否使用了敏感或个人数据及其处理方式] +- **训练中是否涉及人类受试者**：[数据收集中是否涉及人类受试者；IRB 或伦理委员会审查状态] +- **双重用途潜力**：[模型是否可能被挪用于有害用途；已采取的保障措施] +- **社会影响评估**：[更广泛的社会影响——正面和负面] + +## 局限性与建议 + +### 已知局限性 + +- [局限性 1 -- 例如在特定语言或领域上性能不佳] +- [局限性 2 -- 例如上下文窗口限制] +- [局限性 3 -- 例如在特定场景下倾向于产生幻觉] + +### 失败模式 + +- [失败模式 1 -- 模型可预测地失败的条件] +- [失败模式 2 -- 边界情况或对抗性输入] + +### 部署者建议 + +- [建议 1 -- 例如实施输出过滤] +- [建议 2 -- 例如为高风险决策设置人工审核环节] +- [建议 3 -- 例如随时间监测模型漂移] + +--- + +## 审批 + +| 字段 | 值 | +|------|-----| +| 审批人 | [姓名] | +| 日期 | [YYYY-MM-DD] | +| 决定 | [APPROVED / REJECTED / CONDITIONAL] | +| 条件 | [如适用] | + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-PIPIA.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-PIPIA.md new file mode 100644 index 0000000..046d9cc --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-PIPIA.md @@ -0,0 +1,134 @@ +--- +id: PIPIA-YYYY-MM-DD-NNN +title: "[系统/流程] 个人信息保护影响评估" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: low # PIPIA 需要大量人工判断 +review_required: true # 《个人信息保护法》第55条规定的强制性评估 + +# --- 审批工作流（可选，审批时填写）--- +# reviewed_by: <审批人标识> # 邮箱 | github 用户 | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: high +pipl_applicable: true +pipl_article_55_trigger: sensitive_data # sensitive_data | automated_decision | third_party_disclosure | cross_border | public_disclosure | other +pipl_sensitive_data: true +pipl_cross_border_transfer: false +pipl_retention_until: YYYY-MM-DD # 自 created 起至少保留 3 年 +iso_42001_clause: [6, 8] +dpo_consulted: false +tags: [privacy, pipl, china, pipia] +related: [] +--- + +# PIPIA: [系统/流程] 个人信息保护影响评估 + +> **重要提示**：此文档为 AI 代理创建的草稿。在开始任何个人信息处理之前,需经人工审核与批准。 +> 根据《个人信息保护法》第56条,本报告及相关处理情况记录应至少留存 **3 年**。 + +## 第55条触发情形 + +勾选导致此 PIPIA 的触发情形: + +- [ ] 处理 **敏感个人信息**(第28条:生物识别、宗教信仰、特定身份、医疗健康、金融账户、行踪轨迹、不满14周岁未成年人个人信息等) +- [ ] 利用个人信息进行 **自动化决策** +- [ ] 委托处理 / 向其他个人信息处理者提供 / 公开个人信息 +- [ ] **跨境** 提供个人信息 +- [ ] 其他对个人权益有重大影响的处理活动 + +## 处理活动描述 + +- **处理性质**:[数据收集、存储、使用与删除方式] +- **处理范围**:[个人信息主体数量、数据量、地理范围(中国大陆境内/境外)] +- **处理情境**:[与个人信息主体的关系、合理预期] +- **处理目的**:[明确陈述的目的] +- **法律依据(《个人信息保护法》第13条)**:[同意 / 履行合同 / 法定义务 / 应对突发公共卫生事件 / 新闻报道 / 公共利益 / 已公开信息 / 其他] +- **个人信息主体类别**:[员工 / 客户 / 未成年人 / 患者等] +- **个人信息类别**:[身份标识、联系方式、健康、生物识别、金融、位置等] +- **是否涉及敏感个人信息**:[是/否 — 列出第28条所列类别] +- **接收方 / 受托处理方**:[谁接收数据、合同保障措施] +- **保留期限**:[期限、删除条件、保留的合法依据] + +## 必要性与正当性(第56条第1款) + +- **合法性**:[为何处理符合《个人信息保护法》第13条] +- **正当性**:[为何处理具有清晰、合理的目的] +- **必要性**:[为何此为达成目的所需的最小处理] +- **目的限定**:[处理如何限于陈述的目的范围] +- **数据最小化**:[如何仅收集必需的最小信息] + +## 个人权益影响(第56条第2款) + +| 受影响的权利 | 可能性 | 严重程度 | 风险等级 | 缓解措施 | +|------------|------|--------|--------|--------| +| 知情权 / 决定权(第44条) | [低/中/高] | [低/中/高] | [低/中/高] | [措施] | +| 查阅 / 复制权(第45条) | [低/中/高] | [低/中/高] | [低/中/高] | [措施] | +| 更正 / 补充权(第46条) | [低/中/高] | [低/中/高] | [低/中/高] | [措施] | +| 删除权(第47条) | [低/中/高] | [低/中/高] | [低/中/高] | [措施] | +| 可携带权(第45条) | [低/中/高] | [低/中/高] | [低/中/高] | [措施] | +| 退出自动化决策权(第24条) | [低/中/高] | [低/中/高] | [低/中/高] | [措施] | + +## 安全风险(第56条第2款) + +| 风险 | 可能性 | 严重程度 | 风险等级 | 来源 | 影响性质 | +|------|------|--------|--------|------|--------| +| [风险1] | [低/中/高] | [低/中/高] | [低/中/高] | [来源] | [人身/财产/名誉] | +| [风险2] | [低/中/高] | [低/中/高] | [低/中/高] | [来源] | [人身/财产/名誉] | + +## 保护措施(第56条第3款) + +证明所采取的保护措施 **合法、有效,与风险程度相适应**。 + +| 风险 | 措施 | 类型 | 残余风险 | 责任人 | +|------|------|------|--------|--------| +| [风险1] | [缓解措施] | [技术 / 组织 / 合同] | [低/中/高] | [角色/姓名] | +| [风险2] | [缓解措施] | [技术 / 组织 / 合同] | [低/中/高] | [角色/姓名] | + +## 跨境传输分析 + +> 仅当 `pipl_cross_border_transfer: true` 时填写本节。 +> +> 根据《个人信息保护法》第38-40条,跨境提供个人信息须满足以下任一条件:(a) 国家网信部门 **安全评估**,(b) 个人信息保护 **认证**,(c) 与境外接收方订立 **标准合同** 并向省级网信部门备案。 + +- **目的地**:[国家/地区] +- **传输机制**:[security_assessment / certification / standard_contract / other] +- **网信部门安全评估编号**:[备案号或不适用] +- **必要性说明**:[为何数据必须出境] +- **接收方保障**:[对境外接收方施加的合同义务] +- **个人信息主体告知**:[如何告知并取得同意] + +## 自动化决策(第24条) + +> 涉及自动化决策时填写本节。 + +- **决策逻辑披露**:[如何向个人解释逻辑] +- **公平性与透明度**:[如何审计不合理差别待遇] +- **拒绝 / 人工介入权**:[个人如何申请人工干预] +- **营销 / 推送通知**:[如用于个性化营销,如何提供退出途径] + +## 协商 + +- **个人信息保护负责人意见**:[处理超过100万人个人信息时必需 — 第52条] +- **个人信息主体协商**:[是/否] — [方法] +- **省级网信部门协商**:[是/否/不适用] — [备案] + +## 留存与复审 + +- **PIPIA 报告留存截止日期**:[YYYY-MM-DD — 自创建日起至少 3 年] +- **下次复审日期**:[YYYY-MM-DD] +- **复审触发事件**: + - 处理范围或目的变更 + - 新增个人信息类别 + - 法规变化(《个人信息保护法》修订、CAC 指南) + - 安全事件 +- **责任复审人**:[角色/姓名] + +## 批准 + +| 批准人 | 日期 | 决定 | 条件 | +|--------|------|------|------| +| [审核人] | [YYYY-MM-DD] | [批准 / 有条件批准 / 拒绝] | [条件(如有)] | + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-REQ.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-REQ.md new file mode 100644 index 0000000..149c18d --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-REQ.md @@ -0,0 +1,239 @@ +--- +id: REQ-YYYY-MM-DD-NNN +title: [需求标题] +status: draft +created: YYYY-MM-DD +agent: [agent-name-v1.0] +confidence: medium | low +review_required: true +risk_level: low | medium | high +type: functional | non-functional | constraint +priority: must | should | could | wont +stakeholder_type: end_user | operator | acquirer | regulator | maintainer | developer +observability_scope: none # none | basic | full — set when OTel instrumentation is relevant +api_spec_path: "" # Path to OpenAPI/AsyncAPI spec file if this requirement involves APIs +tags: [] +related: [] +validated_by: null +validated_date: null +--- + +# REQ: [需求标题] + +> **提案**：本需求由 AI 智能体提出。 +> 需要经过人工验证。 +> +> **标准对齐**：ISO/IEC/IEEE 29148:2018（需求工程） + +## 描述 + +[对需求的清晰简明描述] + +## 干系人类型 + +识别需求的来源方（依据 ISO/IEC/IEEE 29148:2018 §6.2）： + +- [ ] **最终用户** -- 与系统交互的人员 +- [ ] **操作员** -- 操作系统的人员 +- [ ] **采购方** -- 采购系统的组织 +- [ ] **监管机构** -- 具有监管权限的机构 +- [ ] **维护人员** -- 负责系统维护的人员 +- [ ] **开发人员** -- 构建系统的人员 + +## 需求类型 + +- [ ] 功能性需求 +- [ ] 非功能性需求（参见下方质量特性） +- [ ] 约束条件 + +## 优先级 (MoSCoW) + +- [ ] **必须有** -- MVP 的强制要求 +- [ ] **应该有** -- 重要但非关键 +- [ ] **可以有** -- 如有时间则实现 +- [ ] **不会有** -- 超出当前范围 + +## 理由说明 + +[为什么需要此需求。它解决了什么问题或提供了什么价值] + +## 验收标准 + +1. **假设** [初始上下文] + **当** [用户操作] + **则** [预期结果] + +2. **假设** [初始上下文] + **当** [用户操作] + **则** [预期结果] + +## 非功能性需求 + +> 类别与 ISO/IEC 25010:2023 对齐。完整定义请参见 `00-governance/ISO-25010-2023-REFERENCE.md`。 +> 仅填写与本需求相关的部分。 + +### 功能适宜性 + +- 完备性：[功能覆盖所有指定任务的程度] +- 正确性：[结果所要求的精确度] +- 适当性：[功能促进任务完成的程度] + +### 性能效率 + +- 时间行为：[响应时间、吞吐量要求] +- 资源利用：[内存、CPU、存储约束] +- 容量：[最大限制和负载要求] + +### 兼容性 + +- 共存性：[共享环境约束] +- 互操作性：[需要集成的系统、数据交换格式] + +### 交互能力 + +> *在 ISO 25010:2023 中由"可用性"更名* + +- 适当性可识别性：[用户识别产品是否满足其需求的难易程度] +- 易学性：[学习曲线预期] +- 易操作性：[操作便利性要求] +- 用户差错防护：[错误预防机制] +- 用户参与度：[用户参与和激励要求] +- 包容性：[需要支持的用户特征范围] +- 用户帮助：[帮助和指引要求] +- 自描述性：[自明性要求] + +### 可靠性 + +- 无缺陷性：[正常条件下的预期无故障运行] +- 可用性：[运行时间要求，例如 99.9%] +- 容错性：[硬件/软件故障下的行为] +- 可恢复性：[恢复时间目标、数据恢复要求] + +### 安全性 + +- 机密性：[数据访问控制要求] +- 完整性：[数据保护要求] +- 不可否认性：[审计跟踪要求] +- 可追责性：[操作追踪要求] +- 真实性：[身份验证要求] +- 抗攻击性：[攻击抵御要求] + +### 可维护性 + +- 模块化：[组件隔离要求] +- 可复用性：[复用预期] +- 可分析性：[影响评估要求] +- 可修改性：[修改便利性要求] +- 可测试性：[测试要求] + +### 灵活性 + +> *在 ISO 25010:2023 中由"可移植性"更名* + +- 适应性：[环境适配要求] +- 可安装性：[安装要求] +- 可替换性：[替换要求] +- 可伸缩性：[扩容/缩容处理要求] + +### 安全保障 + +> *ISO 25010:2023 新增 -- 对 AI 系统尤为重要* + +- 运行约束：[安全运行参数] +- 风险识别：[风险检测要求] +- 故障安全：[安全模式/回退要求] +- 危险警告：[警告机制要求] +- 安全集成：[集成过程中的安全要求] + +## 可观测性需求 + +> 当项目使用 OpenTelemetry 或有可观测性需求时填写本节。 +> 使用标签 `observabilidad` 激活。 + +| 需求 | 值 | 备注 | +|------|-----|------| +| 覆盖范围 | [必须生成链路追踪的端点/服务] | [例如"所有公共 API 端点"] | +| 追踪质量 | [具有必需属性的 span 最低百分比] | [例如"95% 的 span 必须包含 service.name、service.version"] | +| 最大追踪延迟 | [追踪可用的最大可接受时间] | [例如"从发射到后端 < 30s"] | +| 保留策略 | [按环境的保留期限] | [例如"prod: 30 天，dev: 7 天"] | +| 关联可观测指标的 SLO | [依赖 OTel 指标的 SLO] | [例如"p99 延迟 < 500ms，通过 OTel 直方图测量"] | + +## 外部接口 + +> 依据 ISO/IEC/IEEE 29148:2018 §9.4.2。记录与外部系统的接口。 + +### 用户接口 + +| 接口 ID | 描述 | 来源 | 协议/格式 | 数据项 | 约束条件 | +|---------|------|------|----------|--------|----------| +| UI-001 | [描述] | [来源] | [协议] | [数据项] | [约束条件] | + +### 硬件接口 + +| 接口 ID | 描述 | 来源 | 协议/格式 | 数据项 | 约束条件 | +|---------|------|------|----------|--------|----------| +| HW-001 | [描述] | [来源] | [协议] | [数据项] | [约束条件] | + +### 软件接口 + +| 接口 ID | 描述 | 来源 | 协议/格式 | 数据项 | 约束条件 | +|---------|------|------|----------|--------|----------| +| SW-001 | [描述] | [来源] | [协议] | [数据项] | [约束条件] | + +### 通信接口 + +| 接口 ID | 描述 | 来源 | 协议/格式 | 数据项 | 约束条件 | +|---------|------|------|----------|--------|----------| +| COM-001 | [描述] | [来源] | [协议] | [数据项] | [约束条件] | + +## 依赖关系 + +| 类型 | ID | 描述 | +|------|-----|------| +| 依赖 | [REQ-XXX] | [描述] | +| 阻塞 | [REQ-XXX] | [描述] | +| 关联 | [ADR-XXX] | [描述] | + +## 约束条件 + +- [技术约束 1] +- [业务约束 1] +- [法规约束（如适用）] + +## 假设前提 + +- [假设 1] +- [假设 2] + +## 可追溯性 + +> 依据 ISO/IEC/IEEE 29148:2018 §6.3。建立从干系人需求到系统需求再到验收测试的可追溯性。 + +| 干系人需求 | 系统需求 | 验收测试 | +|-----------|----------|----------| +| [需求描述] | [REQ-YYYY-MM-DD-NNN] | [TES-YYYY-MM-DD-NNN / TC-NNN] | + +## 验证与确认 + +> 依据 ISO/IEC/IEEE 29148:2018 §6.6。定义每项需求的验证方式。 + +| 需求 ID | 验证方法 | 验收标准 | 负责人 | +|---------|----------|----------|--------| +| [REQ-XXX] | inspection \| analysis \| demonstration \| test | [可度量的标准] | [角色/姓名] | + +## 智能体备注 + +[提出需求的智能体提供的附加上下文、问题或建议] + +--- + +## 验证 + +| 字段 | 值 | +|------|-----| +| 验证人 | [姓名] | +| 日期 | [YYYY-MM-DD] | +| 状态 | [Validated/Rejected/Modified] | +| 备注 | [验证人备注] | + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-SBOM.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-SBOM.md new file mode 100644 index 0000000..4200a19 --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-SBOM.md @@ -0,0 +1,77 @@ +--- +id: SBOM-YYYY-MM-DD-NNN +title: "[系统/组件] AI 软件物料清单" +status: accepted +created: YYYY-MM-DD +agent: [agent-name] +confidence: high +review_required: false # 事实性清单 +risk_level: low +iso_42001_clause: [8] +sbom_format_reference: SPDX-3.0 | CycloneDX-1.6 | custom +system_name: "" +tags: [sbom, supply-chain] +related: [] +--- + +# SBOM: [系统/组件] AI 软件物料清单 + +## AI/ML 组件 + +> 本节对应 CycloneDX `component`，类型为 `type: machine-learning-model`。 + +| 组件名称 | 版本 | 供应商 | 类型 | 许可证 | 风险等级 | 漏洞状态 | 最近审计日期 | +|----------|------|--------|------|--------|----------|----------|-------------| +| [组件 1] | [x.y.z] | [供应商] | model | [许可证] | [Low/Med/High] | [Clean/Vulnerable] | [YYYY-MM-DD] | +| [组件 2] | [x.y.z] | [供应商] | library | [许可证] | [Low/Med/High] | [Clean/Vulnerable] | [YYYY-MM-DD] | +| [组件 3] | [x.y.z] | [供应商] | service | [许可证] | [Low/Med/High] | [Clean/Vulnerable] | [YYYY-MM-DD] | +| [组件 4] | [x.y.z] | [供应商] | dataset | [许可证] | [Low/Med/High] | [Clean/Vulnerable] | [YYYY-MM-DD] | + +## 训练数据来源 + +> 符合 ISO 42001 附录 A.7（AI 系统数据）。 + +| 数据集 | 来源 | 许可证 | 包含个人信息 | 偏差评估摘要 | 数据溯源 | 保留策略 | +|--------|------|--------|-------------|-------------|----------|----------| +| [数据集 1] | [来源] | [许可证] | [是/否] | [摘要] | [溯源信息] | [策略] | +| [数据集 2] | [来源] | [许可证] | [是/否] | [摘要] | [溯源信息] | [策略] | + +## 第三方 AI 服务 + +| 服务 | 供应商 | 用途 | 共享数据 | 已签署数据处理协议 | SLA | 区域 | 合规认证 | +|------|--------|------|----------|-------------------|-----|------|----------| +| [服务 1] | [供应商] | [用途] | [数据类型] | [是/否] | [SLA 条款] | [区域] | [SOC2, ISO 27001 等] | +| [服务 2] | [供应商] | [用途] | [数据类型] | [是/否] | [SLA 条款] | [区域] | [SOC2, ISO 27001 等] | + +## 软件依赖 + +> 建议使用 `syft` 或 `trivy` 等工具自动生成本节内容。 + +| 软件包 | 版本 | 许可证 | 已知漏洞 | 最近更新 | +|--------|------|--------|----------|----------| +| [软件包 1] | [x.y.z] | [许可证] | [CVE-YYYY-NNNNN, ...] | [YYYY-MM-DD] | +| [软件包 2] | [x.y.z] | [许可证] | [无] | [YYYY-MM-DD] | +| [软件包 3] | [x.y.z] | [许可证] | [CVE-YYYY-NNNNN] | [YYYY-MM-DD] | + +## 供应链风险评估 + +> 符合 NIST AI 600-1 第 12 类：价值链与组件集成。 + +- **总体风险等级**: [Low/Medium/High/Critical] + +- **已识别的主要风险**: + - [风险 1：描述] + - [风险 2：描述] + - [风险 3：描述] + +- **缓解措施**: + - [缓解措施 1：描述] + - [缓解措施 2：描述] + - [缓解措施 3：描述] + +- **监控计划**: + - [监控活动 1：频率和责任方] + - [监控活动 2：频率和责任方] + - [监控活动 3：频率和责任方] + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-SEC.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-SEC.md new file mode 100644 index 0000000..e317144 --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-SEC.md @@ -0,0 +1,176 @@ +--- +id: SEC-YYYY-MM-DD-NNN +title: "[系统/组件] 安全评估" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: medium +review_required: true + +# --- 审批工作流（可选，审批时填写）--- +# reviewed_by: <审批人标识> # 邮箱 | github 用户 | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: high +eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable +iso_42001_clause: [6, 8] +threat_model_methodology: STRIDE # STRIDE | PASTA | LINDDUN | custom +owasp_asvs_level: 1 # 1 | 2 | 3 +tags: [security] +related: [] +--- + +# SEC: [系统/组件] 安全评估 + +> **重要提示**：本文件是由 AI 代理创建的草稿。 +> 在继续操作之前，需要经过人工审查和批准。 + +## 范围与目标 + +| 字段 | 值 | +|------|-----| +| 被评估系统 | [系统或组件的名称和版本] | +| 评估类型 | [design review / code review / penetration test / threat model] | +| 评估日期 | [YYYY-MM-DD] | +| 评估人 | [代理名称或人工评估人] | + +**目标**: + +- [本次安全评估的主要目标] +- [次要目标（如适用）] + +**范围内**: + +- [纳入范围的组件、服务或边界] +- [纳入范围的组件、服务或边界] + +**范围外**: + +- [排除在外的组件、服务或边界] +- [排除在外的组件、服务或边界] + +## 威胁模型 + +> 方法论：**STRIDE**（仿冒、篡改、抵赖、信息泄露、拒绝服务、权限提升）。 +> 根据前置元数据中的指示，替换为 PASTA、LINDDUN 或自定义方法论。 + +### 仿冒（Spoofing） + +| 威胁 ID | 描述 | 可能性 (1-5) | 影响 (1-5) | 风险评分 | 缓解措施 | +|---------|------|:-----------:|:---------:|:--------:|----------| +| S-001 | [威胁描述] | [1-5] | [1-5] | [L x I] | [建议的缓解措施] | +| S-002 | [威胁描述] | [1-5] | [1-5] | [L x I] | [建议的缓解措施] | + +### 篡改（Tampering） + +| 威胁 ID | 描述 | 可能性 (1-5) | 影响 (1-5) | 风险评分 | 缓解措施 | +|---------|------|:-----------:|:---------:|:--------:|----------| +| T-001 | [威胁描述] | [1-5] | [1-5] | [L x I] | [建议的缓解措施] | +| T-002 | [威胁描述] | [1-5] | [1-5] | [L x I] | [建议的缓解措施] | + +### 抵赖（Repudiation） + +| 威胁 ID | 描述 | 可能性 (1-5) | 影响 (1-5) | 风险评分 | 缓解措施 | +|---------|------|:-----------:|:---------:|:--------:|----------| +| R-001 | [威胁描述] | [1-5] | [1-5] | [L x I] | [建议的缓解措施] | +| R-002 | [威胁描述] | [1-5] | [1-5] | [L x I] | [建议的缓解措施] | + +### 信息泄露（Information Disclosure） + +| 威胁 ID | 描述 | 可能性 (1-5) | 影响 (1-5) | 风险评分 | 缓解措施 | +|---------|------|:-----------:|:---------:|:--------:|----------| +| I-001 | [威胁描述] | [1-5] | [1-5] | [L x I] | [建议的缓解措施] | +| I-002 | [威胁描述] | [1-5] | [1-5] | [L x I] | [建议的缓解措施] | + +### 拒绝服务（Denial of Service） + +| 威胁 ID | 描述 | 可能性 (1-5) | 影响 (1-5) | 风险评分 | 缓解措施 | +|---------|------|:-----------:|:---------:|:--------:|----------| +| D-001 | [威胁描述] | [1-5] | [1-5] | [L x I] | [建议的缓解措施] | +| D-002 | [威胁描述] | [1-5] | [1-5] | [L x I] | [建议的缓解措施] | + +### 权限提升（Elevation of Privilege） + +| 威胁 ID | 描述 | 可能性 (1-5) | 影响 (1-5) | 风险评分 | 缓解措施 | +|---------|------|:-----------:|:---------:|:--------:|----------| +| E-001 | [威胁描述] | [1-5] | [1-5] | [L x I] | [建议的缓解措施] | +| E-002 | [威胁描述] | [1-5] | [1-5] | [L x I] | [建议的缓解措施] | + +## OWASP ASVS 合规性 + +> 参考：OWASP 应用安全验证标准 (ASVS) 5.0。 +> 按前置元数据中指定的级别（`owasp_asvs_level`）验证控制措施。 + +| 控制 ID | 描述 | 级别 (L1/L2/L3) | 状态 | 证据 | 备注 | +|---------|------|:---------------:|:----:|------|------| +| V1.1.1 | [架构 — 控制措施描述] | L1 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V2.1.1 | [认证 — 控制措施描述] | L1 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V3.1.1 | [会话管理 — 控制措施描述] | L1 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V4.1.1 | [访问控制 — 控制措施描述] | L1 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V5.1.1 | [输入验证 — 控制措施描述] | L1 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V6.1.1 | [存储加密 — 控制措施描述] | L1 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V7.1.1 | [错误处理与日志 — 控制措施描述] | L1 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V8.1.1 | [数据保护 — 控制措施描述] | L1 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V9.1.1 | [通信安全 — 控制措施描述] | L1 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V10.1.1 | [恶意代码 — 控制措施描述] | L2 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V11.1.1 | [业务逻辑 — 控制措施描述] | L2 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V12.1.1 | [文件与资源 — 控制措施描述] | L1 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V13.1.1 | [API 与 Web 服务 — 控制措施描述] | L1 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V14.1.1 | [配置管理 — 控制措施描述] | L1 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V50.1.1 | [OAuth 与 OIDC — 控制措施描述] | L1 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V51.1.1 | [自包含令牌 — 控制措施描述] | L2 | [Pass / Fail / NA] | [链接或引用] | [备注] | +| V52.1.1 | [SAML — 控制措施描述] | L2 | [Pass / Fail / NA] | [链接或引用] | [备注] | + +> 根据需要添加或删除行。重点关注与被评估系统相关的控制措施。 + +## 发现的漏洞 + +| 漏洞 ID | CWE | 严重程度 (CVSS) | 描述 | 受影响组件 | 修复方案 | 状态 | +|---------|-----|:---------------:|------|-----------|----------|:----:| +| VULN-001 | [CWE-XXX] | [0.0-10.0] | [漏洞描述] | [组件或模块] | [修复步骤] | [open / mitigated / accepted] | +| VULN-002 | [CWE-XXX] | [0.0-10.0] | [漏洞描述] | [组件或模块] | [修复步骤] | [open / mitigated / accepted] | +| VULN-003 | [CWE-XXX] | [0.0-10.0] | [漏洞描述] | [组件或模块] | [修复步骤] | [open / mitigated / accepted] | + +## 安全控制措施 + +> 参考：OWASP 软件保障成熟度模型 (SAMM)。 + +| 业务职能 | 实践 | 成熟度级别 (1-3) | 当前状态 | 差距 | +|----------|------|:----------------:|----------|------| +| 治理 | 策略与指标 | [1-3] | [当前状态描述] | [已识别差距] | +| 治理 | 政策与合规 | [1-3] | [当前状态描述] | [已识别差距] | +| 治理 | 教育与指导 | [1-3] | [当前状态描述] | [已识别差距] | +| 设计 | 威胁评估 | [1-3] | [当前状态描述] | [已识别差距] | +| 设计 | 安全需求 | [1-3] | [当前状态描述] | [已识别差距] | +| 设计 | 安全架构 | [1-3] | [当前状态描述] | [已识别差距] | +| 实现 | 安全构建 | [1-3] | [当前状态描述] | [已识别差距] | +| 实现 | 安全部署 | [1-3] | [当前状态描述] | [已识别差距] | +| 实现 | 缺陷管理 | [1-3] | [当前状态描述] | [已识别差距] | +| 验证 | 架构评估 | [1-3] | [当前状态描述] | [已识别差距] | +| 验证 | 需求驱动测试 | [1-3] | [当前状态描述] | [已识别差距] | +| 验证 | 安全测试 | [1-3] | [当前状态描述] | [已识别差距] | +| 运营 | 事件管理 | [1-3] | [当前状态描述] | [已识别差距] | +| 运营 | 环境管理 | [1-3] | [当前状态描述] | [已识别差距] | +| 运营 | 运维管理 | [1-3] | [当前状态描述] | [已识别差距] | + +## 建议 + +| 优先级 | 描述 | 工作量 | 影响 | +|:------:|------|:------:|:----:| +| Critical | [建议描述] | [Low / Medium / High] | [Low / Medium / High] | +| High | [建议描述] | [Low / Medium / High] | [Low / Medium / High] | +| Medium | [建议描述] | [Low / Medium / High] | [Low / Medium / High] | +| Low | [建议描述] | [Low / Medium / High] | [Low / Medium / High] | + +--- + +## 审批 + +| 字段 | 值 | +|------|-----| +| 审批人 | [姓名] | +| 日期 | [YYYY-MM-DD] | +| 决定 | [APPROVED / REJECTED / CONDITIONAL] | +| 附加条件 | [如适用] | + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-TC260RA.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-TC260RA.md new file mode 100644 index 0000000..7d08683 --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-TC260RA.md @@ -0,0 +1,147 @@ +--- +id: TC260RA-YYYY-MM-DD-NNN +title: "[系统] TC260 风险评估" +status: draft +created: YYYY-MM-DD +agent: [agent-name] +confidence: medium +review_required: true + +# --- 审批工作流（可选，审批时填写）--- +# reviewed_by: <审批人标识> # 邮箱 | github 用户 | DID +# reviewed_at: YYYY-MM-DD +# review_outcome: approved # approved | revisions_requested | rejected +risk_level: high +tc260_application_scenario: null # 例如:public_service | healthcare | finance | content_generation | social | safety_critical +tc260_intelligence_level: null # narrow | foundation | agentic | general +tc260_application_scale: null # individual | organization | societal | cross_border +tc260_risk_level: not_applicable # low | medium | high | very_high | extremely_severe | not_applicable +tc260_endogenous_risks: [] +tc260_application_risks: [] +tc260_derivative_risks: [] +iso_42001_clause: [6] +tags: [china, tc260, risk-assessment] +related: [] +--- + +# TC260RA: [系统] TC260 风险评估 + +> **重要提示**:此文档为 AI 代理创建的草稿,需要人工审核与批准。 +> +> 与全国信息安全标准化技术委员会(TC260)于 2025 年 9 月 15 日发布的 **《人工智能安全治理框架 2.0》** 一致。 + +## 1. 四大支柱映射 + +说明本系统如何对应框架的四大支柱: + +| 支柱 | 本系统的覆盖 | +|------|------------| +| **治理原则**(以人为本、AI 向善、安全可控) | [陈述] | +| **风险分类**(技术内生 / 应用 / 衍生) | [参见下方分类] | +| **技术应对** | [参见第4节] | +| **治理措施**(组织实施) | [参见第5节] | + +## 2. 三标准风险分级(5.5节 / 附录1) + +风险等级由 **应用场景 × 智能等级 × 应用规模** 组合得出。 + +### 2.1 应用场景 + +- **选定**:[public_service / healthcare / finance / content_generation / social / safety_critical / industrial_control / other] +- **理由**:[为何此场景适用] + +### 2.2 智能等级 + +| 等级 | 定义 | 本系统 | +|------|------|------| +| Narrow | 单一用途模型 | [ ] | +| Foundation | 通用基础模型(LLM、视觉语言) | [ ] | +| Agentic | 基础模型 + 自主工具使用 | [ ] | +| General | 接近通用人工智能 | [ ] | + +- **选定**:[narrow / foundation / agentic / general] + +### 2.3 应用规模 + +| 规模 | 定义 | 本系统 | +|------|------|------| +| Individual | 单一用户 / 小团队 | [ ] | +| Organization | 单一组织部署 | [ ] | +| Societal | 影响公众的重要部分 | [ ] | +| Cross-border | 跨中国大陆与其他司法辖区运营 | [ ] | + +- **选定**:[individual / organization / societal / cross_border] + +### 2.4 计算所得风险等级 + +| 风险等级 | 描述 | +|---------|------| +| 低(Low) | 预期最小危害;标准控制即可 | +| 中(Medium) | 可预见、有限的危害;需复审与基本应对 | +| 高(High) | 对个人或特定群体有重大风险;需全面控制 | +| 很高(Very High) | 对社会稳定或大规模人群有风险;需行业级监督 | +| 极重(Extremely Severe) | 灾难性 / 系统性危害风险;失控 / 灾难性风险关切 | + +- **计算等级**:[low / medium / high / very_high / extremely_severe] +- **理由**:[结合场景 × 智能 × 规模的推理] + +## 3. 风险分类 + +### 3.1 内生技术风险 + +> 来源于 AI 模型自身:漏洞、偏见、幻觉、鲁棒性不足。 + +| 风险 | 描述 | 可能性 | 严重程度 | 缓解 | +|------|------|------|--------|------| +| [风险1] | [描述] | [低/中/高] | [低/中/高] | [措施] | +| [风险2] | [描述] | [低/中/高] | [低/中/高] | [措施] | + +### 3.2 应用风险 + +> 来源于技术应用方式:误用、范围蔓延、依赖。 + +| 风险 | 描述 | 可能性 | 严重程度 | 缓解 | +|------|------|------|--------|------| +| [风险1] | [描述] | [低/中/高] | [低/中/高] | [措施] | +| [风险2] | [描述] | [低/中/高] | [低/中/高] | [措施] | + +### 3.3 衍生风险 + +> 二阶社会影响:就业替代、舆论塑造、生态破坏。 + +| 风险 | 描述 | 可能性 | 严重程度 | 缓解 | +|------|------|------|--------|------| +| [风险1] | [描述] | [低/中/高] | [低/中/高] | [措施] | +| [风险2] | [描述] | [低/中/高] | [低/中/高] | [措施] | + +## 4. 技术应对 + +将每项优先风险映射到一项或多项技术控制(红队、对齐、内容过滤、GB 45438 水印、模型评估套件、沙箱等)。 + +| 风险编号 | 应对措施 | 责任人 | 验证 | +|---------|---------|------|------| +| [E.1] | [控制] | [角色] | [测试方案 / 指标] | +| [A.1] | [控制] | [角色] | [测试方案 / 指标] | +| [D.1] | [控制] | [角色] | [测试方案 / 指标] | + +## 5. 治理措施 + +- **指定负责人**:[角色 / 姓名] +- **内部报告频率**:[月度 / 季度] +- **升级路径**:[向谁升级及触发条件] +- **开源组件**:[如系统嵌入开源 AI:依据 v2.0 OSS 条款的治理] +- **灾难性风险监测**:[very_high / extremely_severe 等级所需:如何监测失控场景] + +## 6. 监测与复审 + +- **下次复审日期**:[YYYY-MM-DD] +- **复审触发**:[模型版本变更 / 场景扩展 / 规模跃升 / 法规更新] +- **关联文档**:[ETH-..., MCARD-..., AILABEL-..., CACFILE-...] + +## 批准 + +| 批准人 | 日期 | 决定 | 条件 | +|--------|------|------|------| +| [审核人] | [YYYY-MM-DD] | [批准 / 有条件批准 / 拒绝] | [条件(如有)] | + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-TDE.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-TDE.md new file mode 100644 index 0000000..b6c0b0b --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-TDE.md @@ -0,0 +1,145 @@ +--- +id: TDE-YYYY-MM-DD-NNN +title: [技术债务标题] +status: identified # `identified` → `resolved` 当债务偿清时（仅 TDE 的终态） +created: YYYY-MM-DD +agent: [agent-name-v1.0] +confidence: high | medium | low +review_required: false +risk_level: low | medium | high +type: code | architecture | infrastructure | documentation | testing +impact: low | medium | high +effort: low | medium | high +iso_42001_clause: [] # 4 | 5 | 6 | 7 | 8 | 9 | 10 +tags: [] +related: [] +priority: null +assigned_to: null +promoted_from_followup: null # FU-NNN，如果从 .straymark/follow-ups-backlog.md 提升而来 +--- + +# TDE: [技术债务标题] + +> **由代理识别**：优先级排序和任务分配需要人工决策。 +> +> **激活触发条件**（任意一条满足即可——若均不满足，请改在 AILOG 中以 `R (new, not in Charter)` 记录）：先前 Charter 的遗留、横跨多个模块/Charter、需要当前 scope 包络之外的专用 Charter、或需要代理无法独自决定的人工优先级或分配。完整判定请参见 `.straymark/00-governance/AGENT-RULES.md` §3。 + +## 摘要 + +[已识别技术债务的简要描述] + +## 债务类型 + +- [ ] **代码**：难以维护、重复或结构不良的代码 +- [ ] **架构**：次优的架构决策 +- [ ] **基础设施**：有问题的配置或依赖 +- [ ] **文档**：缺失或过时的文档 +- [ ] **测试**：覆盖率不足或脆弱的测试 + +## 位置 + +| 文件/组件 | 描述 | +|-----------|------| +| `path/to/file.ts` | [问题所在] | +| `path/to/component/` | [问题所在] | + +## 问题描述 + +[详细描述为什么这属于技术债务] + +### 观察到的症状 +- [症状 1：例如"该文件超过 1000 行"] +- [症状 2：例如"有 5 个功能几乎相同的函数"] + +### 原始原因 +[该债务产生的原因——如果已知] + +## 影响 + +### 对开发的影响 +- [对开发团队的影响] + +### 对维护的影响 +- [对维护工作的阻碍] + +### 对性能的影响（如适用） +- [性能影响] + +### 对安全的影响（如适用） +- [安全风险] + +## 建议的解决方案 + +[如何解决该问题的描述] + +### 推荐方法 +1. [步骤 1] +2. [步骤 2] +3. [步骤 3] + +### 替代方案 +- [替代方案 1]：[简要描述] +- [替代方案 2]：[简要描述] + +## 估算 + +| 方面 | 值 | 理由 | +|------|-----|------| +| 工作量 | [Low/Medium/High] | [原因] | +| 解决后的影响 | [Low/Medium/High] | [原因] | +| 不解决的风险 | [Low/Medium/High] | [原因] | +| 紧迫性 | [Low/Medium/High] | [原因] | + +## 优先级矩阵（供人工参考） + +``` + │ 低工作量 │ 高工作量 │ +─────────┼─────────────┼─────────────┤ +高 │ 立即执行 │ 规划 │ +影响 │ │ │ +─────────┼─────────────┼─────────────┤ +低 │ 快速解决 │ 考虑 │ +影响 │ │ │ +``` + +## 依赖关系 + +- [应先解决的其他债务] +- [可能受影响的功能] + +## 代理备注 + +[补充上下文、观察或建议] + +--- + +## 优先级决策 + +| 字段 | 值 | +|------|-----| +| 优先级决策人 | [姓名] | +| 日期 | [YYYY-MM-DD] | +| 分配的优先级 | [P1/P2/P3/Backlog/Will not resolve] | +| 迭代/里程碑 | [如适用] | +| 分配给 | [团队/个人] | +| 备注 | [说明] | + +--- + +## 解决记录 (Resolution) + +> 当此处所述的债务被解决时，填写此章节**并**将 frontmatter 的 `status: identified` 翻转为 `resolved`。 +> 保留磁盘上的文档——`resolved` 是 TDE 的规范终态；文件成为审计历史而非被删除。 +> 关于生命周期语义，请见 DOCUMENTATION-POLICY.md §3。 +> +> 当债务仍为 `identified` / `accepted` / superseded 时，请完全省略此章节—— +> 它仅在终态转换时有意义。 + +| 字段 | 值 | +|------|-----| +| 解决者 | [偿清债务的 Charter ID / PR / commit] | +| 日期 | [YYYY-MM-DD] | +| 验证方式 | [如何验证已解决——测试、drift 检查、审计等] | +| 备注 | [未来读者应当知晓的事项，例如部分解决的范围] | + + diff --git a/.straymark/templates/i18n/zh-CN/TEMPLATE-TES.md b/.straymark/templates/i18n/zh-CN/TEMPLATE-TES.md new file mode 100644 index 0000000..06c3786 --- /dev/null +++ b/.straymark/templates/i18n/zh-CN/TEMPLATE-TES.md @@ -0,0 +1,201 @@ +--- +id: TES-YYYY-MM-DD-NNN +title: [测试计划标题] +status: draft +created: YYYY-MM-DD +agent: [agent-name-v1.0] +confidence: medium +review_required: true +risk_level: low | medium +iso_42001_clause: [] # 4 | 5 | 6 | 7 | 8 | 9 | 10 +observability_scope: none # none | basic | full — 当 OTel 插桩相关时设置 +tags: [] +related: [] +--- + +# TES: [测试计划标题] + +> **提案**：本计划由 AI 代理创建，需要经过验证。 +> +> **标准对齐**：ISO/IEC/IEEE 29119-3:2021（软件测试 — 测试文档） +> +> 本模板对应 ISO 29119-3 层次结构中的**测试计划**级别： +> - **组织级测试方针** — 组织范围的测试原则（不在 StrayMark 范围内） +> - **测试策略** — 项目级别的测试策略（可在项目治理中引用） +> - **测试计划** — 本文件：针对特定功能、组件或变更的具体测试规划 + +## 范围 + +### 范围内 +- [待测试的功能/组件 1] +- [待测试的功能/组件 2] + +### 范围外 +- [不测试的内容及原因] + +## 测试方法 + +> *依据 ISO/IEC/IEEE 29119-3:2021。描述本计划的整体测试方法。* + +### 测试设计技术 + +| 技术 | 应用场景 | 选择理由 | +|------|----------|----------| +| 等价类划分 | [应用场景] | [选择原因] | +| 边界值分析 | [应用场景] | [选择原因] | +| 判定表 | [应用场景] | [选择原因] | +| 状态转换 | [应用场景] | [选择原因] | +| 探索性测试 | [应用场景] | [选择原因] | + +### 测试类型与覆盖率 + +| 类型 | 覆盖率 | 工具 | 选择理由 | +|------|--------|------|----------| +| 单元测试 | [%] | [Jest/Vitest 等] | [选择该级别的原因] | +| 集成测试 | [%] | [工具] | [选择该级别的原因] | +| 端到端测试 | [关键用例] | [Cypress/Playwright 等] | [选择这些用例的原因] | +| 性能测试 | [如适用] | [工具] | [需要的原因] | + +### 测试完成标准 + +- [ ] [标准 1，例如"所有关键测试用例通过"] +- [ ] [标准 2，例如"代码覆盖率 >= X%"] +- [ ] [标准 3，例如"无未解决的严重程度 1 级缺陷"] +- [ ] [标准 4，例如"性能在 SLA 阈值范围内"] + +### 测试暂停与恢复标准 + +**暂停标准**（暂停测试的条件）： +- [例如"构建无法部署到测试环境"] +- [例如"关键路径中发现阻塞性缺陷"] + +**恢复标准**（恢复测试的条件）： +- [例如"阻塞性缺陷已解决并验证"] +- [例如"测试环境已恢复且稳定"] + +## 测试用例 + +### 功能：[名称] + +| ID | 用例 | 前置条件 | 步骤 | 预期结果 | 优先级 | +|----|------|----------|------|----------|--------| +| TC-001 | [名称] | [准备工作] | 1. [步骤] | [预期结果] | High | +| TC-002 | [名称] | [准备工作] | 1. [步骤] | [预期结果] | Medium | + +### 负面用例 + +| ID | 用例 | 无效输入 | 预期结果 | +|----|------|----------|----------| +| TC-N01 | [名称] | [输入] | [预期错误] | + +### 边界用例 + +| ID | 用例 | 条件 | 预期结果 | +|----|------|------|----------| +| TC-E01 | [名称] | [边界条件] | [预期结果] | + +## 测试数据需求 + +> 依据 ISO/IEC/IEEE 29119-3:2021。 + +| 数据集 ID | 来源 | 准备步骤 | 敏感度分类 | 保留策略 | +|-----------|------|----------|-----------|----------| +| TD-001 | [来源] | [准备方法] | [公开/内部/机密/受限] | [测试后保留/删除] | +| TD-002 | [来源] | [准备方法] | [分类] | [策略] | + +### 所需测试夹具 +- [夹具 1]：[描述] +- [夹具 2]：[描述] + +### 所需模拟对象 +- [模拟对象 1]：[模拟的内容] +- [模拟对象 2]：[模拟的内容] + +## 测试环境需求 + +> 依据 ISO/IEC/IEEE 29119-3:2021。 + +| 组件 | 版本 | 配置 | 依赖 | +|------|------|------|------| +| [操作系统/运行时] | [版本] | [具体配置] | [所需服务] | +| [数据库] | [版本] | [模式/种子数据] | [连接要求] | +| [外部服务] | [版本/API] | [桩/实际环境] | [认证/网络] | + +- **环境**：[本地/CI/预发布] +- **特殊配置**：[如适用] +- **外部依赖**：[列表] + +## 可观测性测试 + +> 当项目使用 OpenTelemetry 或有可观测性需求时填写本节。 +> 使用标签 `observabilidad` 激活。 + +| 测试 ID | 测试描述 | 预期结果 | 状态 | +|---------|----------|----------|------| +| OBS-01 | 验证内部服务调用间的 W3C Trace Context 传播 | 所有下游请求中包含 `traceparent` 头 | [ ] | +| OBS-02 | 验证外部/异步调用间的 W3C Trace Context 传播 | `traceparent` 通过消息队列和异步流程传播 | [ ] | +| OBS-03 | 验证日志与追踪的关联 | 结构化日志条目中包含 `trace_id` 和 `span_id` | [ ] | +| OBS-04 | 测试负载下的头采样 | 采样率在持续负载下与配置百分比一致 | [ ] | +| OBS-05 | 测试错误场景的尾采样（如适用） | 无论头采样率如何，错误追踪都被捕获 | [ ] | +| OBS-06 | 验证 Collector 中的敏感数据脱敏 | 个人信息、令牌和密钥在到达后端前已脱敏 | [ ] | + +## 验收标准 + +- [ ] 最低覆盖率达到 [X]% +- [ ] 所有关键用例通过 +- [ ] 现有功能无回归 +- [ ] 性能在可接受的阈值范围内 + +## 风险与缓解措施 + +| 风险 | 概率 | 影响 | 缓解措施 | +|------|------|------|----------| +| [风险] | [High/Medium/Low] | [High/Medium/Low] | [措施] | + +## 结果 + +> 使用 ISO/IEC/IEEE 29119-3:2021 术语记录测试文档制品。 + +### 测试执行日志 + +| 用例 ID | 日期 | 测试人 | 结果 | 实际输出 | 备注 | +|---------|------|--------|------|----------|------| +| TC-001 | [日期] | [代理/人工] | [Pass/Fail/Blocked] | [实际结果] | [备注] | + +### 测试事件报告 + +> 记录执行过程中发现的任何缺陷或异常行为。 + +| 事件 ID | 用例 ID | 严重程度 | 描述 | 状态 | +|---------|---------|----------|------|------| +| TI-001 | [TC-XXX] | [Critical/Major/Minor] | [描述] | [Open/Resolved] | + +### 测试状态报告 + +| 指标 | 值 | +|------|-----| +| 测试用例总数 | [N] | +| 通过 | [N] | +| 失败 | [N] | +| 阻塞 | [N] | +| 未执行 | [N] | +| 通过率 | [%] | + +### 测试完成报告 + +- **完成日期**：[YYYY-MM-DD] +- **完成标准是否满足**：[是/否 — 列出未满足的标准] +- **遗留风险**：[未解决事件带来的残余风险] +- **建议**：[发布 / 暂停修复 / 需要额外测试] + +--- + +## 验证 + +| 字段 | 值 | +|------|-----| +| 验证人 | [姓名] | +| 日期 | [YYYY-MM-DD] | +| 备注 | [说明] | + + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..fa24937 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# StrayMark - Universal Agent Configuration + + +> **Read and follow the rules in [STRAYMARK.md](STRAYMARK.md).** +> That file contains all StrayMark documentation governance rules for this project. + +--- + +> **About this file.** `AGENTS.md` is the open standard for guiding AI coding agents, +> donated to the Agentic AI Foundation (Linux Foundation, 2025) and read by Claude Code, +> OpenAI Codex CLI, Cursor, Aider, Devin, Sourcegraph Amp, Google Jules, Zed AI, Continue, +> Roo Code, Factory Droids, GitHub Copilot, Gemini CLI, Windsurf, Amazon Q and others. +> StrayMark keeps this file in sync with `STRAYMARK.md` via `straymark update`. + +## Autonomous Rules (minimum viable — works without STRAYMARK.md) + +### Identity +- Identify yourself with your platform and version in the `agent:` field + (e.g. `claude-code-v1.0`, `gemini-cli-v1.0`, `copilot-v1.0`, `cursor-v1.0`, `codex-cli-v1.0`) +- Declare confidence in decisions: `high | medium | low` + +### Review Requirements +- ETH, ADR, SEC, MCARD, DPIA → always `review_required: true` +- `risk_level: high | critical` → always `review_required: true` + +### Prohibited +- Never document credentials, tokens, API keys, or PII in document content + +### Pre-commit Checklist + +Before committing, check: +- [ ] Changed auth/PII/security code? → Create AILOG (`risk_level: high`) + ETH draft +- [ ] Complex code change? → Run `straymark analyze --output json`; if `above_threshold > 0` create AILOG (fallback if CLI unavailable: >20 lines) +- [ ] Chose between 2+ alternatives? → Create AIDEC +- [ ] Changed public API or DB schema? → Create AILOG + consider ADR +- [ ] Changed ML model/prompts? → Create AILOG + human review +- [ ] Changed OTel instrumentation? → Create AILOG + tag `observabilidad` +- [ ] Starting a multi-session implementation block (>1 day, >5 tasks, multi-phase)? → Declare a Charter via `straymark charter new` (see STRAYMARK.md §15) + +### Regulatory Frontmatter Snippet + +When creating documents for AI-related changes, include applicable fields: + +```yaml +eu_ai_act_risk: not_applicable # unacceptable | high | limited | minimal | not_applicable +nist_genai_risks: [] # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain +iso_42001_clause: [] # 4 | 5 | 6 | 7 | 8 | 9 | 10 +``` + +### NIST AI 600-1 Risk Categories (quick reference) + +1. CBRN Information — 2. Confabulation — 3. Dangerous Content — 4. Data Privacy — 5. Environmental — 6. Harmful Bias — 7. Human-AI Config — 8. Information Integrity — 9. Information Security — 10. Intellectual Property — 11. Obscene Content — 12. Value Chain + +### Observability Rule + +Do not capture PII, tokens, or secrets in OTel attributes or logs. Record instrumentation pipeline changes (new spans, changed attributes, Collector configuration) in AILOG with tag `observabilidad`. + +### File Naming Convention + +``` +[TYPE]-[YYYY-MM-DD]-[NNN]-[description].md +``` + +Example: `AILOG-2026-05-14-001-add-feature.md` + +--- + +*StrayMark | [Strange Days Tech](https://strangedays.tech) — Because every change tells a story.* diff --git a/CLAUDE.md b/CLAUDE.md index b4622d3..a8820d9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,13 +1,13 @@ -# DevTrail - Claude Code Configuration +# StrayMark - Claude Code Configuration - -> **Read and follow the rules in [DEVTRAIL.md](DEVTRAIL.md).** -> That file contains all DevTrail documentation governance rules for this project. - + +> **Read and follow the rules in [STRAYMARK.md](STRAYMARK.md).** +> That file contains all StrayMark documentation governance rules for this project. + --- -## Autonomous Rules (minimum viable — works without DEVTRAIL.md) +## Autonomous Rules (minimum viable — works without STRAYMARK.md) ### Identity - Always identify yourself as `claude-code-v{version}` in the `agent:` field @@ -25,13 +25,13 @@ - **NEVER commit directly to `main`** — all changes go through branches + PRs - Branch prefixes: `feature/`, `feat/`, `fix/`, `hotfix/`, `docs/`, `refactor/`, `test/` - Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`, `perf:` -- Full strategy: `.devtrail/00-governance/GIT-BRANCHING-STRATEGY.md` +- Full strategy: `.straymark/00-governance/GIT-BRANCHING-STRATEGY.md` ### Pre-commit Checklist Before committing, check: - [ ] Changed auth/PII/security code? → Create AILOG (`risk_level: high`) + ETH draft -- [ ] Complex code change? → Run `devtrail analyze --output json`; if `above_threshold > 0` create AILOG (fallback if CLI unavailable: >20 lines) +- [ ] Complex code change? → Run `straymark analyze --output json`; if `above_threshold > 0` create AILOG (fallback if CLI unavailable: >20 lines) - [ ] Chose between 2+ alternatives? → Create AIDEC - [ ] Changed public API or DB schema? → Create AILOG + consider ADR - [ ] Changed ML model/prompts? → Create AILOG + human review @@ -57,7 +57,7 @@ Do not capture PII, tokens, or secrets in OTel attributes or logs. Record instru --- -*DevTrail | [Strange Days Tech](https://strangedays.tech) — Because every change tells a story.* +*StrayMark | [Strange Days Tech](https://strangedays.tech) — Because every change tells a story.* ## Active Technologies - Rust, Edition 2024 + `arborist-metrics` (analysis), `clap` (argument parsing), `serde`/`serde_json` (JSON output), `ignore` (directory traversal + gitignore), `thiserror` (error types) (001-core-cli-mvp) diff --git a/Cargo.toml b/Cargo.toml index 0d14d0f..3806a03 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,7 +8,7 @@ repository = "https://github.com/StrangeDaysTech/arborist-cli" readme = "README.md" keywords = ["complexity", "metrics", "cognitive", "cyclomatic", "cli"] categories = ["command-line-utilities", "development-tools"] -exclude = [".devtrail/", ".github/", ".claude/", ".specify/", "specs/", "tests/fixtures/"] +exclude = [".straymark/", ".github/", ".claude/", ".specify/", "specs/", "tests/fixtures/"] [[bin]] name = "arborist" diff --git a/DEVTRAIL.md b/DEVTRAIL.md deleted file mode 100644 index 761e137..0000000 --- a/DEVTRAIL.md +++ /dev/null @@ -1,355 +0,0 @@ -# DevTrail - Documentation Governance Rules - -> **This file is automatically managed by DevTrail CLI.** -> Read and follow these rules when working on this project. -> For complete rules: `.devtrail/00-governance/AGENT-RULES.md` - ---- - -## Governance Context - -These rules operationalize **ISO/IEC 42001:2023** (AI Management System) — DevTrail's vertebral standard. Following them produces documented evidence compatible with: - -- **EU AI Act** (Regulation 2024/1689) — risk classification, transparency, incident reporting -- **NIST AI RMF 1.0 + 600-1** — risk management functions and generative AI risk profiles -- **GDPR** — data protection impact assessments and privacy safeguards - -> See `AI-GOVERNANCE-POLICY.md` for the full ISO 42001 Annex A control mapping. - ---- - -## 1. Fundamental Principle - -> **"No significant change without a documented trace."** - ---- - -## 2. Language Configuration - -Check `.devtrail/config.yml` for the project's language setting: - -```yaml -language: en # Options: en, es (default: en) -``` - -**Template paths based on language:** - -| Language | Template Path | -|----------|---------------| -| `en` (default) | `.devtrail/templates/TEMPLATE-*.md` | -| `es` | `.devtrail/templates/i18n/es/TEMPLATE-*.md` | - -If the config file doesn't exist or `language` is not set, use English (`en`) as default. - ---- - -## 3. Documentation Reporting - -At the end of each task, you MUST report your DevTrail documentation status: - -**If you created documentation:** -``` -DevTrail: Created AILOG-2025-01-27-001-implement-auth.md -``` - -**If documentation was not needed:** -``` -DevTrail: No documentation required (minor change / below complexity threshold) -``` - -**If you should have documented but didn't:** -``` -DevTrail: Documentation pending - review required -``` - -This transparency helps users verify compliance with DevTrail rules. - ---- - -## 4. Agent Identity - -When working on this project: - -- **Identify yourself** with your platform and version (e.g., `claude-code-v1.0`, `gemini-cli-v1.0`, `copilot-cli-v1.0`) -- **Declare** your confidence level in decisions: `high | medium | low` -- **Record** your identification in the `agent:` field of the metadata - ---- - -## 5. Git Operations - -> **CRITICAL: Never commit directly to `main` branch.** - -All changes must go through feature/fix branches and Pull Requests. - -### Branch Prefixes - -| Prefix | Purpose | -|--------|---------| -| `feature/` or `feat/` | New features | -| `fix/` | Bug fixes | -| `hotfix/` | Urgent production fixes | -| `docs/` | Documentation only | -| `refactor/` | Code refactoring | -| `test/` | Test changes | - -### Conventional Commits - -| Prefix | Use Case | -|--------|----------| -| `feat:` | New feature | -| `fix:` | Bug fix | -| `docs:` | Documentation only | -| `refactor:` | No behavior change | -| `chore:` | Maintenance | - -### Quick Workflow - -```bash -git checkout main && git pull origin main -git checkout -b fix/descriptive-name -# ... make changes and commits ... -git push -u origin fix/descriptive-name -gh pr create --title "fix: description" --body "..." -``` - -> **Full details:** `.devtrail/00-governance/GIT-BRANCHING-STRATEGY.md` - ---- - -## 6. When to Document - -### MANDATORY (create document) - -| Situation | Action | -|-----------|--------| -| Code complexity above threshold | Create AILOG — run `devtrail analyze --output json`; fallback: >20 lines | -| Decision between technical alternatives | Create AIDEC | -| Changes in auth/authorization/PII | Create AILOG (`risk_level: high`) + ETH draft | -| Changes in public API or DB schema | Create AILOG + consider ADR | -| Changes in ML models or AI prompts | Create AILOG + human review | -| Security-critical dependency changes | Create AILOG + human review | -| OTel instrumentation changes | Create AILOG + tag `observabilidad` | - -### DO NOT DOCUMENT - -- Trivial changes (whitespace, typos, formatting) -- Sensitive information (credentials, tokens, API keys) - ---- - -## 7. File Naming Convention - -``` -[TYPE]-[YYYY-MM-DD]-[NNN]-[description].md -``` - -**Example**: `AILOG-2025-01-27-001-implement-oauth.md` - ---- - -## 8. Minimum Metadata - -```yaml ---- -id: AILOG-2026-03-25-001 -title: Brief description -status: accepted -created: 2026-03-25 -agent: your-agent-id-v1.0 -confidence: high | medium | low -review_required: true | false -risk_level: low | medium | high | critical -tags: [oauth, authentication, api] -related: - - ADR-2026-01-20-001-use-jwt-tokens.md -# Optional regulatory fields (activate by context): -# eu_ai_act_risk: not_applicable -# nist_genai_risks: [] -# iso_42001_clause: [] -# observability_scope: none ---- -``` - -### Tags - -- Use **kebab-case** keywords: `sqlite`, `api-design`, `gnome-integration` -- 3 to 8 tags per document — describe topic, technology, or component -- Tags enable search and categorization in `devtrail explore` - -### Related - -- Reference other **DevTrail documents** by filename (with `.md`): `AILOG-2025-01-27-001-implement-oauth.md` -- For documents in subdirectories, include path from `.devtrail/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-file.md` -- For documents in the same directory, filename alone is sufficient -- **Do not** use task IDs, issue numbers, or URLs — those go in the document body - ---- - -## 9. Autonomy Limits - -| Type | Agent can do | Requires human | -|------|----------|----------------| -| **AILOG** | Create freely | — | -| **AIDEC** | Create freely | — | -| **SBOM** | Create freely | — | -| **ETH** | Create draft | Approval | -| **ADR** | Create draft | Review | -| **SEC** | Create draft | Approval (always) | -| **MCARD** | Create draft | Approval (always) | -| **DPIA** | Create draft | Approval (always) | -| **REQ** | Propose | Validation | -| **TES** | Propose | Validation | -| **INC** | Contribute analysis | Conclusions | -| **TDE** | Identify | Prioritize | - ---- - -## 10. Documentation Map - -> **IMPORTANT**: This is the complete project structure. -> Not everything is loaded in this session, but any document can be accessed when needed. - -``` -.devtrail/ -├── 00-governance/ ← POLICIES AND RULES -│ ├── PRINCIPLES.md # Project guiding principles -│ ├── DOCUMENTATION-POLICY.md # Complete documentation policy -│ ├── AGENT-RULES.md # Detailed rules for AI agents -│ └── exceptions/ # Documented exceptions -│ -├── 01-requirements/ ← REQUIREMENTS (REQ) -│ └── [REQ-*.md] # System requirements -│ -├── 02-design/ ← DESIGN -│ └── decisions/ # ADRs (Architecture Decision Records) -│ └── [ADR-*.md] -│ -├── 03-implementation/ ← IMPLEMENTATION GUIDES -│ └── [technical guides] -│ -├── 04-testing/ ← TESTING (TES) -│ └── [TES-*.md] # Test strategies and plans -│ -├── 05-operations/ ← OPERATIONS -│ ├── [runbooks] -│ └── incidents/ # Post-mortems (INC) -│ └── [INC-*.md] -│ -├── 06-evolution/ ← EVOLUTION -│ └── technical-debt/ # Technical debt (TDE) -│ └── [TDE-*.md] -│ -├── 07-ai-audit/ ← AI AGENT AUDIT -│ ├── agent-logs/ # Action logs (AILOG) -│ │ └── [AILOG-*.md] -│ ├── decisions/ # Agent decisions (AIDEC) -│ │ └── [AIDEC-*.md] -│ └── ethical-reviews/ # Ethical reviews (ETH, DPIA) -│ └── [ETH-*.md] -│ -├── 08-security/ ← SECURITY ASSESSMENTS (SEC) -│ └── [SEC-*.md] -│ -├── 09-ai-models/ ← AI MODEL CARDS (MCARD) -│ └── [MCARD-*.md] -│ -├── templates/ ← TEMPLATES (12 types) -│ -└── QUICK-REFERENCE.md ← 1-page quick reference -``` - ---- - -## 11. When to Load Additional Documents - -| Situation | Document to load | -|-----------|------------------| -| Going to create an AILOG | `.devtrail/templates/TEMPLATE-AILOG.md` | -| Going to create an AIDEC | `.devtrail/templates/TEMPLATE-AIDEC.md` | -| Going to create an ADR | `.devtrail/templates/TEMPLATE-ADR.md` | -| Going to create a REQ | `.devtrail/templates/TEMPLATE-REQ.md` | -| Questions about naming or metadata | `.devtrail/00-governance/DOCUMENTATION-POLICY.md` | -| Questions about autonomy limits | `.devtrail/00-governance/AGENT-RULES.md` | -| Need to see existing requirements | List `.devtrail/01-requirements/` | -| Need to see existing ADRs | List `.devtrail/02-design/decisions/` | -| Need to see technical debt | List `.devtrail/06-evolution/technical-debt/` | - ---- - -## 12. Workflow - -``` -1. EVALUATE if the change requires documentation (see section 6) - | - v -2. LOAD the corresponding template (see section 11) - | - v -3. CREATE the document with correct naming - [TYPE]-[YYYY-MM-DD]-[NNN]-[description].md - | - v -4. If risk_level: high/critical or confidence: low - -> Mark review_required: true -``` - ---- - -## 13. Quick Type Reference - -| Prefix | Name | Location | -|--------|------|----------| -| `AILOG` | AI Action Log | `.devtrail/07-ai-audit/agent-logs/` | -| `AIDEC` | AI Decision | `.devtrail/07-ai-audit/decisions/` | -| `ETH` | Ethical Review | `.devtrail/07-ai-audit/ethical-reviews/` | -| `ADR` | Architecture Decision Record | `.devtrail/02-design/decisions/` | -| `REQ` | Requirement | `.devtrail/01-requirements/` | -| `TES` | Test Plan | `.devtrail/04-testing/` | -| `INC` | Incident Post-mortem | `.devtrail/05-operations/incidents/` | -| `TDE` | Technical Debt | `.devtrail/06-evolution/technical-debt/` | -| `SEC` | Security Assessment | `.devtrail/08-security/` | -| `MCARD` | Model/System Card | `.devtrail/09-ai-models/` | -| `SBOM` | Software Bill of Materials | `.devtrail/07-ai-audit/` | -| `DPIA` | Data Protection Impact Assessment | `.devtrail/07-ai-audit/ethical-reviews/` | - ---- - -## 14. Regulatory Alignment - -DevTrail is aligned with the following standards and regulations: - -| Standard | Role in DevTrail | Key Documents | -|----------|-----------------|---------------| -| **ISO/IEC 42001:2023** | Vertebral standard — AI Management System | AI-GOVERNANCE-POLICY.md | -| **EU AI Act** | Risk classification, incident reporting, transparency | ETH, INC, AILOG regulatory fields | -| **NIST AI RMF / 600-1** | Risk management, 12 GenAI risk categories | ETH, AILOG | -| **ISO/IEC 25010:2023** | Software quality model (9 characteristics) | REQ, ADR | -| **ISO/IEC/IEEE 29148:2018** | Requirements engineering | REQ | -| **ISO/IEC/IEEE 29119-3:2021** | Software testing documentation | TES | -| **GDPR** | Data protection and privacy | ETH (Data Privacy) | -| **OpenTelemetry** | Observability (optional, complementary) | Tag `observabilidad` | -| **C4 Model** | Architecture visualization in ADR documents | ADR (Mermaid diagrams) | - -> **Reference**: See `AI-GOVERNANCE-POLICY.md` for the full ISO 42001 Annex A mapping to DevTrail documents. - ---- - -## Directive Injection Markers - -DevTrail uses HTML comment markers to manage injected content in agent configuration files (CLAUDE.md, GEMINI.md, .cursorrules, etc.): - -```html - -... managed content ... - -``` - -- Content between these markers is managed by `devtrail init`, `update`, and `repair` -- Do not remove or modify these markers manually — they are required for safe updates -- If markers are missing from a target file, DevTrail appends the content block at the end - ---- - -*DevTrail | [GitHub](https://github.com/StrangeDaysTech/devtrail)* -*[Strange Days Tech](https://strangedays.tech) — Because every change tells a story.* diff --git a/GEMINI.md b/GEMINI.md index 2cbe8b2..8a696aa 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,13 +1,13 @@ -# DevTrail - Gemini CLI Configuration +# StrayMark - Gemini CLI Configuration - -> **Read and follow the rules in [DEVTRAIL.md](DEVTRAIL.md).** -> That file contains all DevTrail documentation governance rules for this project. - + +> **Read and follow the rules in [STRAYMARK.md](STRAYMARK.md).** +> That file contains all StrayMark documentation governance rules for this project. + --- -## Autonomous Rules (minimum viable — works without DEVTRAIL.md) +## Autonomous Rules (minimum viable — works without STRAYMARK.md) ### Identity - Always identify yourself as `gemini-cli-v{version}` in the `agent:` field @@ -24,11 +24,12 @@ Before committing, check: - [ ] Changed auth/PII/security code? → Create AILOG (`risk_level: high`) + ETH draft -- [ ] Complex code change? → Run `devtrail analyze --output json`; if `above_threshold > 0` create AILOG (fallback if CLI unavailable: >20 lines) +- [ ] Complex code change? → Run `straymark analyze --output json`; if `above_threshold > 0` create AILOG (fallback if CLI unavailable: >20 lines) - [ ] Chose between 2+ alternatives? → Create AIDEC - [ ] Changed public API or DB schema? → Create AILOG + consider ADR - [ ] Changed ML model/prompts? → Create AILOG + human review - [ ] Changed OTel instrumentation? → Create AILOG + tag `observabilidad` +- [ ] Starting a multi-session implementation block (>1 day, >5 tasks, multi-phase)? → Declare a Charter via `straymark charter new` (see STRAYMARK.md §15) ### Regulatory Frontmatter Snippet @@ -50,4 +51,4 @@ Do not capture PII, tokens, or secrets in OTel attributes or logs. Record instru --- -*DevTrail | [Strange Days Tech](https://strangedays.tech) — Because every change tells a story.* +*StrayMark | [Strange Days Tech](https://strangedays.tech) — Because every change tells a story.* diff --git a/STRAYMARK.md b/STRAYMARK.md new file mode 100644 index 0000000..0dbeebd --- /dev/null +++ b/STRAYMARK.md @@ -0,0 +1,476 @@ +# StrayMark - Documentation Governance Rules + +> **This file is automatically managed by StrayMark CLI.** +> Read and follow these rules when working on this project. +> For complete rules: `.straymark/00-governance/AGENT-RULES.md` + +--- + +## Why these rules exist + +StrayMark externalizes the cognitive discipline of senior software engineering — explicit scope, declared decisions, named risks, recorded alternatives, audited trails — into versioned files that live alongside the code. The intent is to constrain the agent's decision space so AI-assisted work stays coherent across many turns instead of drifting into hidden technical debt. + +As a side effect of doing the engineering work this way, the artifacts produced map cleanly onto the major AI governance frameworks. The rules are written for the engineering work first; the compliance evidence is what falls out when the work is done with discipline. + +**Frameworks the resulting evidence aligns with:** + +- **ISO/IEC 42001:2023** (AI Management System) — vertebral standard for governance structure +- **EU AI Act** (Regulation 2024/1689) — risk classification, transparency, incident reporting +- **NIST AI RMF 1.0 + 600-1** — risk management functions and generative AI risk profiles +- **GDPR** — data protection impact assessments and privacy safeguards + +**Optional regional scope** — when `.straymark/config.yml` declares `regional_scope: china`, the framework additionally produces evidence for: + +- **TC260 AI Safety Governance Framework v2.0** — risk grading (TC260RA) +- **PIPL** (Personal Information Protection Law) — PIPIA, retention ≥ 3 years +- **GB 45438-2025** *(mandatory)* — AI-generated content labeling (AILABEL) +- **CAC Algorithm Filing** — algorithm registration (CACFILE) +- **GB/T 45652-2025** — pre-training & fine-tuning data security +- **CSL 2026** — cybersecurity incident reporting (1h / 4h+72h+30d windows) + +> See `AI-GOVERNANCE-POLICY.md` for the ISO 42001 Annex A control mapping and `CHINA-REGULATORY-FRAMEWORK.md` for the China coverage matrix. The product-level rationale lives in [`Propuesta/straymark-design-principles.md`](https://github.com/StrangeDaysTech/straymark/blob/main/Propuesta/straymark-design-principles.md). + +--- + +## 1. Fundamental Principle + +> **"No significant change without a documented trace — and a constrained decision space for the agent."** + +--- + +## 2. Language Configuration + +Check `.straymark/config.yml` for the project's language setting: + +```yaml +language: en # Options: en, es, zh-CN (default: en) +``` + +**Template paths based on language:** + +| Language | Template Path | +|----------|---------------| +| `en` (default) | `.straymark/templates/TEMPLATE-*.md` | +| `es` | `.straymark/templates/i18n/es/TEMPLATE-*.md` | +| `zh-CN` | `.straymark/templates/i18n/zh-CN/TEMPLATE-*.md` | + +If the config file doesn't exist or `language` is not set, use English (`en`) as default. + +--- + +## 3. Documentation Reporting + +At the end of each task, you MUST report your StrayMark documentation status: + +**If you created documentation:** +``` +StrayMark: Created AILOG-2025-01-27-001-implement-auth.md +``` + +**If documentation was not needed:** +``` +StrayMark: No documentation required (minor change / below complexity threshold) +``` + +**If you should have documented but didn't:** +``` +StrayMark: Documentation pending - review required +``` + +This transparency helps users verify compliance with StrayMark rules. + +--- + +## 4. Agent Identity + +When working on this project: + +- **Identify yourself** with your platform and version (e.g., `claude-code-v1.0`, `gemini-cli-v1.0`, `copilot-cli-v1.0`) +- **Declare** your confidence level in decisions: `high | medium | low` +- **Record** your identification in the `agent:` field of the metadata + +--- + +## 5. Git Operations + +> **CRITICAL: Never commit directly to `main` branch.** + +All changes must go through feature/fix branches and Pull Requests. + +### Branch Prefixes + +| Prefix | Purpose | +|--------|---------| +| `feature/` or `feat/` | New features | +| `fix/` | Bug fixes | +| `hotfix/` | Urgent production fixes | +| `docs/` | Documentation only | +| `refactor/` | Code refactoring | +| `test/` | Test changes | + +### Conventional Commits + +| Prefix | Use Case | +|--------|----------| +| `feat:` | New feature | +| `fix:` | Bug fix | +| `docs:` | Documentation only | +| `refactor:` | No behavior change | +| `chore:` | Maintenance | + +### Quick Workflow + +```bash +git checkout main && git pull origin main +git checkout -b fix/descriptive-name +# ... make changes and commits ... +git push -u origin fix/descriptive-name +gh pr create --title "fix: description" --body "..." +``` + +> **Full details:** `.straymark/00-governance/GIT-BRANCHING-STRATEGY.md` + +--- + +## 6. When to Document + +### MANDATORY (create document) + +| Situation | Action | +|-----------|--------| +| Code complexity above threshold | Create AILOG — run `straymark analyze --output json`; fallback: >20 lines | +| Decision between technical alternatives | Create AIDEC | +| Changes in auth/authorization/PII | Create AILOG (`risk_level: high`) + ETH draft | +| Changes in public API or DB schema | Create AILOG + consider ADR | +| Changes in ML models or AI prompts | Create AILOG + human review | +| Security-critical dependency changes | Create AILOG + human review | +| OTel instrumentation changes | Create AILOG + tag `observabilidad` | +| Multi-session implementation block (>1 day, >5 tasks across phases) | Declare a **Charter** — `straymark charter new`. See section 15. | +| Transversal technical debt — heritage from prior Charter, applies to multiple modules, or requires dedicated Charter to remediate | Create **TDE** — distinct from per-Charter `R`. See `.straymark/00-governance/AGENT-RULES.md` §3 for TDE vs `R` disambiguation. | + +### DO NOT DOCUMENT + +- Trivial changes (whitespace, typos, formatting) +- Sensitive information (credentials, tokens, API keys) + +--- + +## 7. File Naming Convention + +``` +[TYPE]-[YYYY-MM-DD]-[NNN]-[description].md +``` + +**Example**: `AILOG-2025-01-27-001-implement-oauth.md` + +--- + +## 8. Minimum Metadata + +```yaml +--- +id: AILOG-2026-03-25-001 +title: Brief description +status: accepted +created: 2026-03-25 +agent: your-agent-id-v1.0 +confidence: high | medium | low +review_required: true | false +risk_level: low | medium | high | critical +tags: [oauth, authentication, api] +related: + - ADR-2026-01-20-001-use-jwt-tokens.md +# Optional regulatory fields (activate by context): +# eu_ai_act_risk: not_applicable +# nist_genai_risks: [] +# iso_42001_clause: [] +# observability_scope: none +--- +``` + +### Tags + +- Use **kebab-case** keywords: `sqlite`, `api-design`, `gnome-integration` +- 3 to 8 tags per document — describe topic, technology, or component +- Tags enable search and categorization in `straymark explore` + +### Related + +- Reference other **StrayMark documents** by filename (with `.md`): `AILOG-2025-01-27-001-implement-oauth.md` +- For documents in subdirectories, include path from `.straymark/`: `07-ai-audit/agent-logs/daemon/AILOG-2026-02-03-001-file.md` +- For documents in the same directory, filename alone is sufficient +- **Do not** use task IDs, issue numbers, or URLs — those go in the document body + +--- + +## 9. Autonomy Limits + +| Type | Agent can do | Requires human | +|------|----------|----------------| +| **AILOG** | Create freely | — | +| **AIDEC** | Create freely | — | +| **SBOM** | Create freely | — | +| **ETH** | Create draft | Approval | +| **ADR** | Create draft | Review | +| **SEC** | Create draft | Approval (always) | +| **MCARD** | Create draft | Approval (always) | +| **DPIA** | Create draft | Approval (always) | +| **REQ** | Propose | Validation | +| **TES** | Propose | Validation | +| **INC** | Contribute analysis | Conclusions | +| **TDE** | Identify | Prioritize | +| **PIPIA** *(china)* | Create draft | Approval (always) | +| **CACFILE** *(china)* | Create draft | Approval (always — counsel + compliance officer before submission) | +| **TC260RA** *(china)* | Create draft | Approval (always) | +| **AILABEL** *(china)* | Create draft | Approval (always — before deployment) | +| **Charter** | Scaffold via `charter new`; fill scope, files, risks, tasks | Operator owns the *trigger* and lifecycle transitions (`declared` → `in-progress` → `closed`). See section 15. | + +--- + +## 10. Documentation Map + +> **IMPORTANT**: This is the complete project structure. +> Not everything is loaded in this session, but any document can be accessed when needed. + +``` +.straymark/ +├── 00-governance/ ← POLICIES AND RULES +│ ├── PRINCIPLES.md # Project guiding principles +│ ├── DOCUMENTATION-POLICY.md # Complete documentation policy +│ ├── AGENT-RULES.md # Detailed rules for AI agents +│ └── exceptions/ # Documented exceptions +│ +├── 01-requirements/ ← REQUIREMENTS (REQ) +│ └── [REQ-*.md] # System requirements +│ +├── 02-design/ ← DESIGN +│ └── decisions/ # ADRs (Architecture Decision Records) +│ └── [ADR-*.md] +│ +├── 03-implementation/ ← IMPLEMENTATION GUIDES +│ └── [technical guides] +│ +├── 04-testing/ ← TESTING (TES) +│ └── [TES-*.md] # Test strategies and plans +│ +├── 05-operations/ ← OPERATIONS +│ ├── [runbooks] +│ └── incidents/ # Post-mortems (INC) +│ └── [INC-*.md] +│ +├── 06-evolution/ ← EVOLUTION +│ └── technical-debt/ # Technical debt (TDE) +│ └── [TDE-*.md] +│ +├── 07-ai-audit/ ← AI AGENT AUDIT +│ ├── agent-logs/ # Action logs (AILOG) +│ │ └── [AILOG-*.md] +│ ├── decisions/ # Agent decisions (AIDEC) +│ │ └── [AIDEC-*.md] +│ ├── ethical-reviews/ # Ethical reviews (ETH, DPIA, PIPIA*) +│ │ └── [ETH-*.md] +│ ├── regulatory-filings/ # CAC algorithm filings (CACFILE*) +│ │ └── [CACFILE-*.md] +│ └── risk-assessments/ # TC260 risk assessments (TC260RA*) +│ └── [TC260RA-*.md] +│ +├── 08-security/ ← SECURITY ASSESSMENTS (SEC) +│ └── [SEC-*.md] +│ +├── 09-ai-models/ ← AI MODEL CARDS (MCARD) +│ ├── [MCARD-*.md] +│ └── labeling/ # GB 45438 content labeling plans (AILABEL*) +│ └── [AILABEL-*.md] +│ +├── charters/ ← CHARTERS — BOUNDED UNITS OF WORK +│ ├── [NN-slug.md] # Declarative ex-ante scope (filename: NN-slug.md, NOT TYPE-YYYY-...) +│ └── [NN-slug.telemetry.yaml] # Post-close telemetry (created by `straymark charter close`) +│ +├── templates/ ← TEMPLATES (12 base + 4 China* + Charter) + +* Only created when regional_scope: china is enabled in .straymark/config.yml. +│ +└── QUICK-REFERENCE.md ← 1-page quick reference +``` + +--- + +## 11. When to Load Additional Documents + +| Situation | Document to load | +|-----------|------------------| +| Going to create an AILOG | `.straymark/templates/TEMPLATE-AILOG.md` | +| Going to create an AIDEC | `.straymark/templates/TEMPLATE-AIDEC.md` | +| Going to create an ADR | `.straymark/templates/TEMPLATE-ADR.md` | +| Going to create a REQ | `.straymark/templates/TEMPLATE-REQ.md` | +| Questions about naming or metadata | `.straymark/00-governance/DOCUMENTATION-POLICY.md` | +| Questions about autonomy limits | `.straymark/00-governance/AGENT-RULES.md` | +| Need to see existing requirements | List `.straymark/01-requirements/` | +| Need to see existing ADRs | List `.straymark/02-design/decisions/` | +| Need to see technical debt | List `.straymark/06-evolution/technical-debt/` | +| Going to declare a Charter | `.straymark/templates/charter/charter-template.md` (or `straymark charter new`) | +| Need to see existing Charters | `straymark charter list` (or list `.straymark/charters/`) | +| SpecKit user — when does a feature yield a Charter? | `.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md` | +| Wondering why agents surface things you didn't ask | `.straymark/00-governance/EMERGENT-OBSERVATION-DESIGN.md` | + +--- + +## 12. Workflow + +``` +1. EVALUATE if the change requires documentation (see section 6) + | + v +2. LOAD the corresponding template (see section 11) + | + v +3. CREATE the document with correct naming + [TYPE]-[YYYY-MM-DD]-[NNN]-[description].md + | + v +4. If risk_level: high/critical or confidence: low + -> Mark review_required: true +``` + +--- + +## 13. Quick Type Reference + +| Prefix | Name | Location | +|--------|------|----------| +| `AILOG` | AI Action Log | `.straymark/07-ai-audit/agent-logs/` | +| `AIDEC` | AI Decision | `.straymark/07-ai-audit/decisions/` | +| `ETH` | Ethical Review | `.straymark/07-ai-audit/ethical-reviews/` | +| `ADR` | Architecture Decision Record | `.straymark/02-design/decisions/` | +| `REQ` | Requirement | `.straymark/01-requirements/` | +| `TES` | Test Plan | `.straymark/04-testing/` | +| `INC` | Incident Post-mortem | `.straymark/05-operations/incidents/` | +| `TDE` | Technical Debt | `.straymark/06-evolution/technical-debt/` | +| `SEC` | Security Assessment | `.straymark/08-security/` | +| `MCARD` | Model/System Card | `.straymark/09-ai-models/` | +| `SBOM` | Software Bill of Materials | `.straymark/07-ai-audit/` | +| `DPIA` | Data Protection Impact Assessment | `.straymark/07-ai-audit/ethical-reviews/` | +| `Charter` | Bounded unit of work (filename `NN-slug.md`, not `TYPE-YYYY-…`) | `.straymark/charters/` | + +--- + +## 14. Regulatory Alignment + +StrayMark is aligned with the following standards and regulations: + +| Standard | Role in StrayMark | Key Documents | +|----------|-----------------|---------------| +| **ISO/IEC 42001:2023** | Vertebral standard — AI Management System | AI-GOVERNANCE-POLICY.md | +| **EU AI Act** | Risk classification, incident reporting, transparency | ETH, INC, AILOG regulatory fields | +| **NIST AI RMF / 600-1** | Risk management, 12 GenAI risk categories | ETH, AILOG | +| **ISO/IEC 25010:2023** | Software quality model (9 characteristics) | REQ, ADR | +| **ISO/IEC/IEEE 29148:2018** | Requirements engineering | REQ | +| **ISO/IEC/IEEE 29119-3:2021** | Software testing documentation | TES | +| **GDPR** | Data protection and privacy | ETH (Data Privacy) | +| **OpenTelemetry** | Observability (optional, complementary) | Tag `observabilidad` | +| **C4 Model** | Architecture visualization in ADR documents | ADR (Mermaid diagrams) | + +> **Reference**: See `AI-GOVERNANCE-POLICY.md` for the full ISO 42001 Annex A mapping to StrayMark documents. + +--- + +## 15. Charters — bounded units of work + +A **Charter** is StrayMark's artifact for an *implementation block that is too big to track as a single AILOG and too small to deserve its own product spec*. It pairs **declarative ex-ante scope** (files to modify, risks, tasks, effort estimate) with **ex-post telemetry** (drift detection, external audit, lessons learned). Concretely: the kind of work that takes >1 day, spans >5 tasks, or crosses multiple sessions where an agent might lose the thread. + +Charters are **conceptually distinct** from the 12+4 document types listed in section 13: + +- They live at `.straymark/charters/NN-slug.md` (sequential prefix, not date-prefix). +- Their lifecycle is `declared` → `in-progress` → `closed`, persisted in frontmatter as the source of truth. +- Telemetry sits beside them as `NN-slug.telemetry.yaml`, written by `straymark charter close`. +- External audits resolve to `.straymark/audits/CHARTER-NN/` and merge back into telemetry. + +### When to declare a Charter + +Trigger row in section 6 names the heuristic; expanded: + +- The work spans **more than one working session** and you need a stable scope contract you can drift-check at close. +- The work has **5+ named tasks** with a topological order (e.g., a SpecKit `tasks.md`). +- The work warrants **external audit** at completion (cross-model review, cross-team review). +- You want **measurable telemetry**: time-to-close, drift count, lessons that feed forward. + +### Charter lifecycle + +| Stage | What happens | CLI | +|-------|--------------|-----| +| **Declared** | Operator scaffolds Charter, fills scope/files/risks/tasks. Status `declared`. | `straymark charter new` | +| **In progress** | Operator flips status to `in-progress` when execution starts. Day-to-day work continues to produce AILOGs. | (manual frontmatter edit) | +| **Batch update** *(multi-batch only, fw-4.14.0+)* | For Charters spanning 3+ batches or >1 day, the AILOG carries a `## Batch Ledger` with one `### Batch N` entry per batch starting as `(pending)`. After each batch commit lands, fill the entry **before pushing** so the AILOG update and the work ride the same push. Single-batch Charters skip this step entirely. | `straymark charter batch-complete CHARTER-NN ` | +| **Drift check** | Before closing, verify declared files vs. actual git diff. AILOG-suppressed paths are noise-filtered; pending `### Batch N` entries cause a hard fail (`--no-batch-ledger-check` bypasses). | `straymark charter drift` | +| **External audit** *(optional)* | Generate prompt → run N auditor CLIs → consolidate → merge into telemetry. | `straymark charter audit` + `/straymark-audit-prompt` + `/straymark-audit-execute` + `/straymark-audit-review` | +| **Closed** | Telemetry yaml emitted; status flips to `closed`; charter is now an audit artifact. | `straymark charter close` | + +### How Charters relate to existing artifacts + +- A Charter **does not replace** AILOGs. AILOGs document individual blocks of code work; the Charter wraps them as a unit. `originating_ailogs:` in the Charter frontmatter declares which AILOGs the Charter contains. +- A Charter **does not replace** ADRs. ADRs document architectural decisions; a Charter may reference them in `originating_spec` or in body sections. +- A Charter **bridges SpecKit features** (`specs/NNN-feature/spec.md`) and execution. See `.straymark/00-governance/SPECKIT-CHARTER-BRIDGE.md` for granularity heuristics and creation timing. + +### Quick CLI surface + +```bash +straymark charter new # scaffold a Charter (interactive) +straymark charter list # enumerate Charters with status/effort/origin +straymark charter status CHARTER-NN # detailed view of one Charter +straymark charter drift CHARTER-NN # file-vs-commit drift, AILOG-aware + Batch Ledger gate +straymark charter batch-complete CHARTER-NN # fill AILOG `## Batch Ledger` Batch (multi-batch only) +straymark charter audit CHARTER-NN # multi-model external audit (orchestration only) +straymark charter close CHARTER-NN # record telemetry; flip status to `closed` +straymark charter refresh-suggest # SpecKit refresh recommendation (chain-level, fw-4.16.0+) — see §15.A +straymark charter amend CHARTER-NN # scaffold post-close Batch N.4 amendment (fw-4.16.0+) — see §15.B +``` + +> **Schema**: `.straymark/schemas/charter.schema.v0.json` (declarative) and `.straymark/schemas/charter-telemetry.schema.v0.json` (telemetry). Both are experimental v0 — patterns crystallize after validation against a second domain (Principle #12). + +### §15.A — Pre-declare SpecKit refresh *(fw-4.16.0+)* + +Multi-Charter modules accumulate spec drift over time. After 3+ Charters in a chain, SpecKit artifacts (`plan.md`, `data-model.md`, `contracts/*`, `quickstart.md`, `research.md`) authored at chain start tend to lag behind the implementation. The fix is a dedicated **refresh PR** between Charter-N close and Charter-(N+1) declare that integrates accumulated learnings into `research.md` (categorized buckets: reusable patterns, code gaps, discipline patterns, empirical corrections) and ratifies operator decisions. The next Charter's `## Context` cites each learning by id. + +**Trigger heuristic** — adopt when (a) chain length ≥ 3 closed Charters in the module AND (b) rolling mean of `agent_quality.r_n_plus_one_emergent_count` across last 3 > 6 AND (c) no refresh PR landed since the chain's branch point. Run: + +```bash +straymark charter refresh-suggest # read-only — prints recommendation +``` + +**Telemetry** — `charter_telemetry.pre_declare_refresh:` (optional, opt-in). See `.straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md` Pattern 1 for full mechanics. + +### §15.B — Post-close audit-driven amendment (Batch N.4) *(fw-4.16.0+)* + +External audit cycles run post-close. When Critical or High findings arrive after a Charter has been marked `status: closed`, the bounded remediation pattern is a **Batch N.4 amendment** that rides on the same execute branch: a new AILOG documents the amendment, the original AILOG receives a `## Historical correction` subsection pointing forward, and the telemetry gains a `post_close_amendment:` block. Apply only when (a) findings are Critical/High, (b) the Charter's closure criterion is materially unmet, AND (c) the fix surface fits in one cohesive PR (~< 25 files, no architectural reopen). Larger or architectural fixes warrant a new Charter. + +```bash +straymark charter amend CHARTER-NN \ # scaffolds the new AILOG, edits the original, prints YAML + --trigger external_audit \ + --findings-closed 5 \ + --ailog-title "post-close remediation — DI wiring + retry" +``` + +The command does not touch git — the operator decides when to commit. The `straymark charter audit --merge-reports --merge-into ` path tolerates `external_audit: []` placeholders in v0.2+ schema so the round-trip with `post_close_amendment` is smooth. See `.straymark/00-governance/CHARTER-CHAIN-EVOLUTION.md` Pattern 2 for full mechanics. + +--- + +## Directive Injection Markers + +StrayMark uses HTML comment markers to manage injected content in agent configuration files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.cursorrules`, `.cursor/rules/straymark.md`): + +```html + +... managed content ... + +``` + +- Content between these markers is managed by `straymark init`, `update`, and `repair` +- Do not remove or modify these markers manually — they are required for safe updates +- If markers are missing from a target file, StrayMark appends the content block at the end +- **Missing-target behavior** *(refined in fw-4.16.2 / cli-3.14.1)*: `straymark init`, `straymark update-framework`, and `straymark repair` all walk `dist-manifest.yml::injections:` and **create any missing target file** (with the marker block) per individual target — a single deleted directive file like `AGENTS.md` is restored without needing to re-run init or remove anything else. There is no opt-out per target short of editing the manifest. *(Historical note: through `cli-3.14.0` / `fw-4.16.1`, `straymark repair` was gated on `STRAYMARK.md` being absent and would silently skip a per-target restore; that gate was removed in `cli-3.14.1`.)* +- `AGENTS.md` is the open standard donated to the Agentic AI Foundation (Linux Foundation, 2025) and is read by Claude Code, OpenAI Codex CLI, Cursor, Aider, Devin, Sourcegraph Amp, Google Jules, Zed AI, Continue, Roo Code, Factory Droids, GitHub Copilot, Gemini CLI, Windsurf, Amazon Q and others. CLI-specific files (`CLAUDE.md`, `GEMINI.md`, etc.) coexist with `AGENTS.md` and provide platform-specific identity strings. + +--- + +*StrayMark | [GitHub](https://github.com/StrangeDaysTech/straymark)* +*[Strange Days Tech](https://strangedays.tech) — Because every change tells a story.*