sdlckit 0.2.0__py3-none-any.whl

engine/__init__.py

@@ -0,0 +1,157 @@
+"""SDLCKit Engine — config, lifecycle, SAGE loop, initiative orchestration."""
+
+__version__ = "0.2.0"
+
+from engine.config.loader import (
+    detect_inline_secrets,
+    load_lifecycle_config,
+    resolve_env_vars,
+)
+from engine.lifecycle.context_resolver import ContextResolver, build_dependency_graph
+from engine.errors import (
+    ConfigError,
+    ConfigWarning,
+    ContextError,
+    CyclicDependencyError,
+    PluginError,
+    StateTransitionError,
+)
+from engine.lifecycle.feedback import FeedbackManager
+from engine.sage.gate_check import extract_sections, run_gate_pass1
+from engine.sage.loop_check import evaluate_loop_checks
+from engine.normalized_hash import normalized_hash
+from engine.models import (
+    Acknowledgment,
+    DimensionScore,
+    BudgetConfig,
+    ConnectorConfig,
+    DefaultsConfig,
+    DependencyGraph,
+    DimensionConfig,
+    EngineConfig,
+    FeedbackSignal,
+    GateCheckConfig,
+    GateCheckResult,
+    SAGEConfig,
+    InputDef,
+    LoopCheckConfig,
+    LoopCheckResult,
+    OverridesConfig,
+    PhaseConfig,
+    PhaseProvision,
+    PhaseRecord,
+    PhaseState,
+    LifecycleConfig,
+    LifecycleState,
+    PluginManifest,
+    PluginRef,
+    ReconciliationBudget,
+    ReconciliationPhaseEntry,
+    ReconciliationPlan,
+    ReconciliationSession,
+    RetryPolicy,
+    ScorerOutput,
+    SkillManifest,
+    StageConfig,
+    StalenessRecord,
+    SkillValidationResult,
+    TokenUsage,
+)
+from engine.sage.skill_loader import (
+    load_all_skills,
+    load_skill,
+    scan_required_sections,
+    validate_scorer_output,
+    validate_skill,
+)
+from engine.config.plugins import (
+    get_phase_plugin,
+    load_all_plugins,
+    load_plugin_manifest,
+)
+from engine.lifecycle.reconciliation import ReconciliationManager
+from engine.lifecycle.manager import StateManager
+
+__all__ = [
+    # Version
+    "__version__",
+    # Config Loader
+    "load_lifecycle_config",
+    "resolve_env_vars",
+    "detect_inline_secrets",
+    # Plugin Loader
+    "load_plugin_manifest",
+    "load_all_plugins",
+    "get_phase_plugin",
+    # State Manager
+    "StateManager",
+    # Context Resolver
+    "ContextResolver",
+    "build_dependency_graph",
+    # SAGE — Gate Check
+    "run_gate_pass1",
+    "extract_sections",
+    # SAGE — Loop Check
+    "evaluate_loop_checks",
+    # Feedback & Reconciliation
+    "FeedbackManager",
+    "ReconciliationManager",
+    # Normalized Hash
+    "normalized_hash",
+    # Errors
+    "ConfigError",
+    "ConfigWarning",
+    "PluginError",
+    "StateTransitionError",
+    "CyclicDependencyError",
+    "ContextError",
+    # Models — Config
+    "LifecycleConfig",
+    "PhaseConfig",
+    "SAGEConfig",
+    "DimensionConfig",
+    "LoopCheckConfig",
+    "GateCheckConfig",
+    "PluginRef",
+    "ConnectorConfig",
+    "DefaultsConfig",
+    "BudgetConfig",
+    "OverridesConfig",
+    "EngineConfig",
+    "RetryPolicy",
+    # Models — Plugin
+    "PluginManifest",
+    "PhaseProvision",
+    "InputDef",
+    # Models — State
+    "LifecycleState",
+    "PhaseRecord",
+    "PhaseState",
+    "TokenUsage",
+    "StalenessRecord",
+    "Acknowledgment",
+    # Models — Feedback & Reconciliation
+    "FeedbackSignal",
+    "ReconciliationPlan",
+    "ReconciliationPhaseEntry",
+    "ReconciliationSession",
+    "ReconciliationBudget",
+    # Models — Stage
+    "StageConfig",
+    # Models — Graph
+    "DependencyGraph",
+    # Models — Results
+    "GateCheckResult",
+    "LoopCheckResult",
+    # SAGE — Skill Loader
+    "load_skill",
+    "load_all_skills",
+    "validate_skill",
+    "validate_scorer_output",
+    "scan_required_sections",
+    # Models — Skill
+    "SkillManifest",
+    "DimensionScore",
+    "ScorerOutput",
+    "SkillValidationResult",
+]

engine/cli.py

@@ -0,0 +1,246 @@
+"""SDLCKit CLI — entry point for sdlckit commands.
+
+Provides the `sdlckit` console script registered via pyproject.toml.
+Currently supports a single subcommand:
+
+  sdlckit init [TARGET] [--force] [--minimal]
+
+The CLI parses arguments with argparse, delegates to the appropriate
+engine module, and translates return values into shell exit codes:
+  0 — success (all files processed)
+  1 — partial success (some files skipped due to user modifications)
+  2 — fatal error (target not found, unrecoverable failure)
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+import engine
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sdlckit",
+        description="SDLCKit — AI-governed SDLC lifecycle engine",
+    )
+    parser.add_argument(
+        "--version", "-V",
+        action="version",
+        version=f"sdlckit {engine.__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # init subcommand
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Initialize a repository for SDLCKit",
+        description="Scaffold a repository with SDLCKit runtime files, lifecycle config, and integration.",
+    )
+    init_parser.add_argument(
+        "target",
+        nargs="?",
+        default=".",
+        help="Target directory to initialize (default: current directory)",
+    )
+    init_parser.add_argument(
+        "--force", "-f",
+        action="store_true",
+        help="Overwrite all files including user-modified; creates .bak backups",
+    )
+    init_parser.add_argument(
+        "--minimal", "-m",
+        action="store_true",
+        help="Install only schemas, lifecycle config, and integration file",
+    )
+    init_parser.add_argument(
+        "--type", "-t",
+        dest="init_type",
+        choices=["component", "initiative"],
+        default="component",
+        help="Project type: component (default) or initiative",
+    )
+    init_parser.add_argument(
+        "--harness",
+        choices=["claude", "codex", "copilot", "cursor", "windsurf", "generic"],
+        default=None,
+        help="Target AI harness (auto-detected if omitted)",
+    )
+
+    # observe subcommand
+    observe_parser = subparsers.add_parser(
+        "observe",
+        help="Create a new observation",
+        description="Record an operational observation for cross-phase feedback.",
+    )
+    observe_parser.add_argument("title", help="Observation title")
+    observe_parser.add_argument("--description", "-d", default="", help="Observation body text")
+    observe_parser.add_argument(
+        "--source", "-s",
+        choices=["incident", "monitoring", "customer", "post-mortem", "manual"],
+        default="manual",
+        help="Observation source (default: manual)",
+    )
+    observe_parser.add_argument(
+        "--severity",
+        choices=["low", "medium", "high"],
+        default="medium",
+        help="Severity level (default: medium)",
+    )
+    observe_parser.add_argument(
+        "--components", "-c",
+        nargs="+",
+        required=True,
+        help="Affected component names",
+    )
+    observe_parser.add_argument("--tags", nargs="*", default=[], help="Optional tags")
+    observe_parser.add_argument(
+        "--state-dir",
+        default=".sdlckit",
+        help="State directory (default: .sdlckit)",
+    )
+
+    # assign subcommand
+    assign_parser = subparsers.add_parser(
+        "assign",
+        help="Import an assignment into a component repo",
+        description="Import an assignment file, creating a work directory and branch.",
+    )
+    assign_parser.add_argument("path", help="Path to the assignment markdown file")
+    assign_parser.add_argument(
+        "--work-dir",
+        default=".sdlckit/work",
+        help="Work directory (default: .sdlckit/work)",
+    )
+
+    # archive subcommand
+    archive_parser = subparsers.add_parser(
+        "archive",
+        help="Pre-merge cleanup for initiative or component repos",
+        description="Archive an initiative or component work item, updating manifests and cleaning up runtime state.",
+    )
+    archive_parser.add_argument("name", help="Initiative name or work item name to archive")
+    archive_parser.add_argument(
+        "--mode",
+        choices=["initiative", "component"],
+        default=None,
+        help="Archive mode (auto-detected if not specified)",
+    )
+    archive_parser.add_argument(
+        "--project-root",
+        default=".",
+        help="Project root directory (default: current directory)",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point. Returns exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    if args.command == "init":
+        if args.init_type == "initiative":
+            from engine.init.scaffolder import run_init_initiative
+            return run_init_initiative(target_dir=args.target)
+        from engine.init.harness import detect_harness
+        from engine.init.scaffolder import run_init
+        harness = args.harness
+        if harness is None:
+            from pathlib import Path
+            harness = detect_harness(Path(args.target).resolve())
+        if harness is None:
+            print("Could not auto-detect AI harness. Use --harness to specify one of: "
+                  "claude, codex, copilot, cursor, windsurf, generic", file=sys.stderr)
+            return 2
+        return run_init(
+            target_dir=args.target,
+            force=args.force,
+            minimal=args.minimal,
+            harness=harness,
+        )
+
+    if args.command == "observe":
+        from pathlib import Path
+        from engine.initiative.observation import create_observation
+        obs_dir = Path(args.state_dir) / "observations"
+        try:
+            path = create_observation(
+                obs_dir,
+                title=args.title,
+                description=args.description,
+                source=args.source,
+                severity=args.severity,
+                components=args.components,
+                tags=args.tags,
+            )
+            print(f"Observation created: {path}")
+            return 0
+        except Exception as e:
+            print(f"Error: {e}", file=sys.stderr)
+            return 2
+
+    if args.command == "assign":
+        from pathlib import Path
+        from engine.initiative.assignment import import_assignment
+        try:
+            dest = import_assignment(Path(args.path), Path(args.work_dir))
+            print(f"Assignment imported: {dest}")
+            return 0
+        except Exception as e:
+            print(f"Error: {e}", file=sys.stderr)
+            return 2
+
+    if args.command == "archive":
+        from pathlib import Path
+        from engine.initiative.archive import archive_component, archive_initiative
+        root = Path(args.project_root)
+        mode = args.mode
+        if mode is None:
+            if (root / "sdlc-initiative.yaml").exists():
+                mode = "initiative"
+            elif (root / "sdlc.yaml").exists():
+                mode = "component"
+            else:
+                print("Error: cannot detect mode — no sdlc.yaml or sdlc-initiative.yaml found", file=sys.stderr)
+                return 2
+        try:
+            if mode == "initiative":
+                result = archive_initiative(args.name, root)
+            else:
+                result = archive_component(args.name, root)
+            if result.warnings:
+                for w in result.warnings:
+                    print(f"Warning: {w}", file=sys.stderr)
+            if result.manifest_updated:
+                print(f"Manifest updated: {args.name} → archived")
+            if result.profile_diffs:
+                print(f"Profile diffs to review: {len(result.profile_diffs)}")
+                for d in result.profile_diffs:
+                    print(f"  {d}")
+            if result.knowledge_diffs:
+                print(f"Knowledge diffs to review: {len(result.knowledge_diffs)}")
+                for d in result.knowledge_diffs:
+                    print(f"  {d}")
+            if result.dirs_removed:
+                print(f"Directories removed: {len(result.dirs_removed)}")
+                for d in result.dirs_removed:
+                    print(f"  {d}")
+            return 0
+        except Exception as e:
+            print(f"Error: {e}", file=sys.stderr)
+            return 2
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

engine/config/__init__.py

@@ -0,0 +1,12 @@
+"""Configuration loading — lifecycle config, plugins, secret detection."""
+
+from engine.config.loader import (
+    detect_inline_secrets,
+    load_lifecycle_config,
+    resolve_env_vars,
+)
+from engine.config.plugins import (
+    get_phase_plugin,
+    load_all_plugins,
+    load_plugin_manifest,
+)

engine/config/_secret_detector.py

@@ -0,0 +1,66 @@
+"""Inline secret pattern detection (internal module)."""
+
+import math
+import re
+
+KNOWN_PREFIXES = (
+    "xoxb-",
+    "xoxp-",
+    "xoxa-",
+    "ghp_",
+    "gho_",
+    "ghs_",
+    "sk-",
+    "AKIA",
+    "rk_live_",
+    "rk_test_",
+    "pk_live_",
+    "pk_test_",
+)
+
+_BASE64_PATTERN = re.compile(r"^[A-Za-z0-9+/=]{32,}$")
+_ALNUM_PATTERN = re.compile(r"^[A-Za-z0-9]{40,}$")
+
+
+def _shannon_entropy(s: str) -> float:
+    """Calculate Shannon entropy in bits per character."""
+    if not s:
+        return 0.0
+    freq: dict[str, int] = {}
+    for c in s:
+        freq[c] = freq.get(c, 0) + 1
+    length = len(s)
+    return -sum(
+        (count / length) * math.log2(count / length) for count in freq.values()
+    )
+
+
+def detect_inline_secret(value: str) -> bool:
+    """Check if a string value matches known secret patterns.
+
+    Returns True if value matches:
+    - Known token prefixes (Slack, GitHub, OpenAI, AWS, Stripe)
+    - High-entropy alphanumeric strings (>40 chars, entropy > 4.0 bits/char)
+    - Base64 blobs (>32 chars matching base64 character set)
+    """
+    if not isinstance(value, str):
+        return False
+
+    # Skip env var references — they're the recommended approach
+    if value.startswith("${") and value.endswith("}"):
+        return False
+
+    # Check known prefixes
+    for prefix in KNOWN_PREFIXES:
+        if value.startswith(prefix):
+            return True
+
+    # Check high-entropy alphanumeric strings
+    if _ALNUM_PATTERN.match(value) and _shannon_entropy(value) > 4.0:
+        return True
+
+    # Check base64 blobs
+    if _BASE64_PATTERN.match(value):
+        return True
+
+    return False